Issues

Issue #1309 resolved

Trouble documenting a module called rst

Thomas Kluyver
created an issue

We have a module in IPython called rst (it's a rst exporter for IPython notebooks). I'm including that in a list using the autosummary extension, like so:

.. autosummary::
   :toctree: generated

   ...
   IPython.nbconvert.exporters.rst
   ...

However, because .rst is the file extension for source files, the table of contents is looking for a document named IPython.nbconvert.exporters. This results in several warnings during the build:

reading sources... [100%] whatsnew/version1.0                                              
source/api/generated/gen.txt:3: WARNING: toctree references unknown document u'api/generated/IPython.nbconvert.exporters'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/takluyver/Code/ipython/docs/source/api/generated/IPython.nbconvert.exporters.rst.rst:: WARNING: document isn't included in any toctree
...
done
preparing documents... done
writing output... [100%] whatsnew/version1.0                                               
<autosummary>:None: WARNING: toctree contains reference to nonexisting document u'api/generated/IPython.nbconvert.exporters'
None:None: WARNING: toctree contains reference to nonexisting document u'api/generated/IPython.nbconvert.exporters'
writing additional files... genindex py-modindex search interactive/htmlnotebook

The toctree directive has a similar issue, but there I can work around it by doubling up the last part ....rst.rst. Doing that in the autosummary directive breaks the link to the module.

I initially saw this in 1.1.3, but I've just reproduced it with my up-to-date Sphinx checkout, which describes itself as 1.2b3.

Comments (2)

  1. Log in to comment