CODEWITHSUNDEEP
pythonpython-sphinxglobtoctree
hllau
hllau

Reputation: 10569

Using Sphinx to generate Python document using :glob:

I am new to Sphinx.

The file /home/user/myproject/docs/source/index.rst is as following:

My project contents:

.. toctree::
   :glob:

   *

I am getting the below message on running $ make html under /home/user/myproject/docs/:

checking consistency... /home/user/myproject/docs/source/design/index.rst:: WARNING: document isn't included in any toctree

What have I done wrongly? I would like Sphinx to automatically generate the structure depending on the directory hierarchy.

Upvotes: 4

Views: 2583

Answers (2)

ryanjdillon
ryanjdillon

Reputation: 18988

If you are willing to just dump all your source files in source without a folder hierarchy, this is possible. Alternatively you could write a routine and run it from the Makefile before the call to sphinx-build.

As Mike alluded to, :glob: will just pull files in alphabetically by filename. See the docs here.

You can use “globbing” in toctree directives, by giving the glob flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically.

If you want to use :glob: and maintain ordering with all your files in source, you'll need to prefix your .rst files with numbers.

Example

source
├── index.html
├── 1_intro.rst
├── 2_install.rst
└── 3_more-than-you-want-to-know.rst

Though, you will of course need to rename the files if you decide you want them ordered differently, rather than moving the order of an explicit list in index.rst.

Upvotes: 0

Mike Graham
Mike Graham

Reputation: 76793

I don't think this is a supported operation.

Fortunately, it's not a very desirable one either, since you generally want the parts of your documentation to appear in a particular order.

Upvotes: 1

Related Questions