Develop Reference

Transclude function documentation into page in sphinx

I have a medium-sized python project that I'm currently documenting using sphinx with the autodoc extension. I have the basics down, the generated documentation looks reasonable.
I have now come across an interesting documentation problem: I have some JSON input file that contains configuration of some sorts. It contains several sections that are used in different parts of my application. I figured the best way to keep the documentation up to date is to document configuration options as close to the point of their usage as possible.
On the other hand, I'd really like to have a single page describing the complete input file structure.
I figured it would be nice if I could somehow "transclude" the relevant documentation blocks into this page so that it shows up both in this page and within the respective module documentation pages like so:
a.py:
def fn_using_A():
'''documentation for config parameter paramA
'''
pass
b.py
def fn_using_B():
'''documentation for config parameter paramB
'''
The input file format documentation page should look somewhat like this:
paramB
------
documentation for config parameter paramB
paramA
------
documentation for config parameter paramA
I would like to not have links/references to the respective functions/modules/whatever but a verbatim copy of the documentation without having to actually copy the documentation into the respective .rst file.
It would be even better to only transclude a part of the documentation I can mark somehow within my code documentation.
I tried using reST's replace feature, writing
def fn_handling_C():
'''fn documentation
.. |paramC_documentation| replace:: foo bar baz
'''
in my code and using |paramC_documentation| within the .rst file that documents my input file format, but generating the documentation yields an error message to the effect that the replacement pattern isn't known. That doesn't surprise me since autodoc doesn't generate full .rst files for modules which are parsed together with manually written .rst files.
Is there a way to achieve this with sphinx?

I ended up writing my own sphinx extension. I used sphinx-todo as basis and modified that to my liking.

using :ref: in Python docstrings using Sphinx

I'm using Sphinx to document a python project, and I'm trying to create a reusable tip to be used in several locations.
Typically, I'll use the following syntax in a python file:
"""
.. tip::
I want this tip to be used in several locations. Why?
- Save time
- Work less
"""
Now this works whether I put it at the beginning of the file, right under class definition or right under function definition.
I found Sphinx's manual for :ref:, which suggests to use a label:
.. _my_reusable_tip:
.. tip::
...
And then call this tip with :ref:`my_reusable_tip` anywhere I want.
The manual states that 'it works across files, when section headings are changed, and for all builders that support cross-references'
The thing is, it doesn't matter in which .py file in the project I write the label and tip definition, the :ref:`my_reusable_tip` just displays 'my_reusable_tip', and not the tip itself.
What I'm using to build the documentation is
sphinx-apidoc -f -F -o
make html
I'm pretty sure my logic is flawed in some way, but I can't figure out why.
I know that Sphinx searches the project for reStructuredText and renders it if it can, but I think I'm missing something here.
I tried to add this label in a seperate .py file enclosed in """, and in a separate .txt file without enclosed """.
I tried creating an .rst file with the label definition and rebuild the html documentation.
What am I missing here?
Python 3.4.3 BTW.

In sphinx, a :ref: is simply a more robust way of linking (or referencing) another part of the document. Thus, your use of :ref: will simply provide a hyperlink to the label.
It is not a way of substituting or expanding a block.
Inline substitutions are available using using |...|, however an inline substitution cannot be used to substitute a block as you seem to require.
RestructuredText is not a template language, and thus doesn't provide macro like facilities. In the event you need it, an alternative solution is to use a template library such as mako or jinja to deal with this kind of issue.

Just using reStructuredText directive
.. include:: ./my_reusable_tip.txt
in your rst files?

Sphinx automodule to show module name?

I've used .. automodule:: mypath.mymodule in my documentation. I wanted the plain module docstring with no other information for members. The module docstring appears, however no indication of the name of the module and no special paragraph formatting.
Is there a standard way to include the name of the actual module and maybe emphasis that particular paragraph as to distinguish it from normal text?

I'd say that the "standard" way is to add a heading with the module name:
mypath.mymodule
===============
.. automodule:: mypath.mymodule
Examples from some packages (click on "Show Source" to see the reST markup):
Celery: http://docs.celeryproject.org/en/latest/reference/celery.events.html
PyMongo: http://api.mongodb.org/python/current/api/bson/index.html
matplotlib: http://matplotlib.org/api/dates_api.html

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.

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.

If you are willing to just dump all your source files in source without a folder heirarchy, 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.

Parsing .rst files with Sphinx-specific directives programmatically

I would like to be able to parse sphinx based rst in Python for further processing and checking. Something like:
import sphinx
p = sphinx.parse("/path/to/file.rst")
do_something_with(p)
It seems that something is possible in docutils using the docutils.core.publish_file:
publish_file(open("/path/to/file.rst")
But that doesn't know anything about sphinx specific directives etc...

You can use Sphinx Extensions to do custom processing before the final write. There is a very good getting started example project in the documentation that discusses various hooks that allow you to customize Sphinx.
Depending on what you're trying to do, you may need to supply your do_something function as a call back argument to one of these events.
doctree-resolved(app, doctree, docname)
html-page-context(app, pagename, templatename, context, doctree)
And then you can extend sphinx as follows
def setup(app):
app.connect('doctree-resolved', do_something)
If the example in the Sphinx tutorial is not detailed enough, Doug Hellmann also has a blog post about creating a spell checker for Sphinx. I found it to be a useful reference for the Sphinx extension I had to write a while back.