toctree subpages, not sections

[Peter Parente]

Hi,

I was wondering if there's a way to configure a toctree directive so
that it includes sub-documents listed in sub-toctrees, but not sub-
sections within those documents.

For example, instead of seeing the following generated for a toctree
directive:

* Doc 1
* Doc 1, Section 1
* Doc 1, Section 2
* Doc 2
* Doc 2, Section 1
* Doc 2, Section 2
* Doc 2, Section 3
* Doc 3
* Doc 3, Subdoc 1
* Doc 3, Subdoc 2

I'd like to see:

* Doc 1
* Doc 2
* Doc 3
* Doc 3, Subdoc 1
* Doc 3, Subdoc 2

Thanks,
Pete

[V!ctor Adan]

hello Pete,

I'm new to Sphinx, so not sure that this is the best answer, but i think that if you use three .. toctree:: directives, one for each of your 'Doc N' bullets, you can do this. e.g.

.. toctree::
:maxdepth: 1

doc1/index


.. toctree::
:maxdepth: 1

doc2/index


.. toctree::
:maxdepth: 2

doc3/index



hope this helps.

victor.

[Guenter Milde]

On 2009-06-10, V!ctor Adan wrote:
> On Wed, Jun 10, 2009 at 08:47:18AM -0700, Peter Parente wrote:

>> I was wondering if there's a way to configure a toctree directive so
>> that it includes sub-documents listed in sub-toctrees, but not sub-
>> sections within those documents.

...

>> I'd like to see:

>> * Doc 1
>> * Doc 2
>> * Doc 3
>> * Doc 3, Subdoc 1
>> * Doc 3, Subdoc 2

> .. toctree::
> :maxdepth: 1

> doc1/index

[ you can leav this out
> .. toctree::
> :maxdepth: 1
GM]
> doc2/index

> .. toctree::
> :maxdepth: 2

> doc3/index

Günter

[Peter Parente]

Thanks for the insight. I see the approach you're taking now with
multiple toctree directives. The problem is that I gave an
oversimplified example of my real TOC structure. What about the
following example, where I'd like:

* Doc1
* Doc2
* Doc3
* Doc3, Sec1
* Doc3, Sec2
* Doc4
* Doc4, Sec1
* Doc4, Sec2
* Doc5
* Doc6
* Doc7
* Doc8
* Doc9
* Doc10
* Doc10, Sec1
* Doc10, Sec2
* Doc11
* Doc11, Sec1
* Doc11, Sec2
* Doc12

to render as:

* Doc1
* Doc2
* Doc3
* Doc4
* Doc5
* Doc6
* Doc7
* Doc8
* Doc9
* Doc10
* Doc11
* Doc12

I see two problems here with multiple toctrees. First, each toctree
directive resets TOC level back to zero. If I give Doc5 its own root
in a toctree it'll render at the same level as Doc1 and Doc2, for
example. Second, Doc5 is listed in a sub-toctree in Doc2. With two
toctrees in this root Doc0, say, it'll appear once as a child of Doc2
(peer of 3 and 4) and then again as the root of a toc for 5, 6, and 7.

[Georg Brandl]

Hi Peter,

I see what you're describing. This wasn't possible, but I've now added
a "titlesonly" option to toctree that will cut everything but document
titles. Usage is like this::

.. toctree::
:titlesonly:

document
names
like
always

It will be in 1.0.

Georg

Peter Parente schrieb:

[Peter Parente]

Wonderful, Georg. Thank you for the new feature.