[sphinx] generating doc from neighboring folders

[alb]

Hi there,

we are evaluating the possibility to use Sphinx and rst to document our
projects. What we have is a project structure that would look like this:

./sandbox/project/
├── components
│   ├── module1
│   │   ├── doc
│   │   │   └── module1.rst
│   │   └── src
│   └── module2
│       ├── doc
│       │   └── module2.rst
│       └── src
└── doc
    └── spec
        ├── conf.py
        └── project_spec.rst


Since components are reusable amongs projects, we would like to get them
documented properly with their own conf.py, but then how would it be possible to
'include' them in the project documentation (under project/doc)?

It looks like sphinx wants all the sources under the same directory root.

What we thought of is writing a python script to traverse the project folder and
look for rst files and _copy_ them in the doc directory, but I find this
solution rather ugly.

Any ideas on how we should organize the rst files to accomplish that?

As a side note, I would like to include automatically links to my components
documentation in the index.rst file, any suggestion on how to do that?

Any suggestion/hint/comment is appreciated.

Al

-- 
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?