These are notes that I put together from an unconference meetup of persons with an interest in Open Source documentation. This is from Google Summer of Code Mentor's summit 2014. Decided to share it here with the goal of benefitting more persons (I did share it on Twitter back then but that isn't as archive friendly).
Open Source Documentation - Types of documentation, best practices and tools
If we're going to try to write modular reusable docs (e.g. using include as here) then maybe a format geared toward reuse is more appropriate; e.g. DITA.
or in other words PLEASE NO...
Looks a bit on the heavy side for me. Good to know about though, perhaps it might be useful for a customer.
DITA is for technical documentation and technically skilled editors but not for maintaining any type of documentation for any kind of open-source project.
-aj
Based on my very cursory research, authoring DITA XML is best done with something like Adobe Framemaker, again makes it seem heavy to me.
There is a simple-minded rst2dita transform.
However I wouldn't consider using it unless Sphinx had support for it (which it doesn't look like it does).
I was mainly mentioning it as a format that is built around the concept of authoring reusable topics meant to be combined into larger documents. Because we're starting to try this using .. include: directives (e.g. here), and this doesn't work nicely (it results in duplicate ids).
@jean whatever is available, first keep it simple (dita isn't, even if transformed) , author great docs (there is plenty of room for improvements) and then we can come back and play around with more exotic technologies.
Or IOW first things first, focusing on writing docs not fighting tools.
Sure, please forget I mentioned DITA, the point is that .. include:: the way we do now doesn't work.
Using .inc files to include from (or another technique from the StackOverflow question I linked) might work, but we'd have to figure out how to author with that in mind.
You are trying to fix it from the wrong site 
The reason why include is in your opinion not working has nothing to do withinclude but with the docs and the structure of the docs itself.
include is doing exactly what is is supposed to do in the training docs.
Nor DITA or other software will help you here ....
I will do a long write up on how to fix all that when I'll be back in Europe next week, so please stay calm and enjoy tea/coffee, there will be a bit work involved but it is not that bad .
BTW, you should attended my trainings, I had a long chapter were I explained all this
1 Like
Well, if you include something with a heading in it, you get duplicate labels. So yes, if you structure the docs so that you aren't including headings, it works fine. That's not practical for transcluding a chapter though.
Cool 
I was very interested in attending, unfortunately the trainings I was involved in clashed.
How's that writeup coming along? 