Include a commented Python script into a Sphinx-generated documentation

Question

I work on a Python project whose html-online-documentation I generate using Sphinx. The project also contains several Python scripts showing examples about how to use the tools contained, while all of these files are commented extensively to explain what it going on.

I would now like to include these example scripts in my documentation as well so that I can reuse them as a tutorial, and do not have to alter both the examples and the tutorial when I apply changes to the code, but can have both things directly together and always up-to-date.

I imagine Sphinx to parse the scripts from top to bottom, and generate an html file out of it, while the comments are shown as text on the page and the code is depicted within code blocks.

Does anyone of you know how this could be achieved?

Thank your very much for your help!

*I imagine Sphinx to parse the scripts from top to bottom, and generate an html file out of it, while the comments are shown as text on the page and the code is depicted within code blocks.* Sphinx has no facility for automatic documentation of scripts. `automodule` is for documenting *modules*, and it works by importing the modules. Scripts are not supposed to be imported. What might work for you is to simply use `literalinclude` to include the verbatim contents of the script file in the documentation. — mzjn, Jun 28 '15 at 07:10
@mzjn Well, then I will probably do this, I'll post it once I've succeeded. But I'm still curious: does the reason why this is not included lie in the structure and/or way how Sphinx works, or is this feature intentionally left out because it would be some kind of bad style? — mindm49907, Jul 01 '15 at 07:16
`automodule` is the Sphinx equivalent of the functionality provided by API documentation tools (such as Epydoc). These tools do not have any facility for automatic documentation of scripts (commented or not) either. Modules/classes/functions have docstrings (which describe the 'contract' of an API), and they are processed by all these tools. Comments (in scripts or modules) are different; they are usually not intended for users of your program/API. — mzjn, Jul 02 '15 at 18:29
A module can function as a script with a `if __name__ == '__main__':` guard at the end. If this is something for you, then the answer to this question might be of interest: http://stackoverflow.com/q/30780334/407651. — mzjn, Jul 02 '15 at 18:31

score 1 · Answer 1 · edited Apr 17 '20 at 00:20

You can use the viewcode sphinx extension for your purpose.

For example:

Say you have a module - BeautifulSoup.py

and you create a file BeautifulSoup.rst with the following content (to generate the documentation for the module)

.. automodule:: BeautifulSoup
    :members:

Once you enable this extension in conf.py, like below, and build html:

extensions = ['sphinx.ext.autodoc', 
    'sphinx.ext.pngmath',
    'sphinx.ext.viewcode',
    ]

You will see a link called [source] next to the class and members, like this:

enter image description here

Clicking on the [source] takes you to the html of your source. Sphinx essentially generates a HTML of your code in the following directory

_build/html/_modules/BeautifulSoup.html

So you can even put an explicit link to this page in your tutorials.

The only thing this will not do is split the doc strings into regular text and code into code blocks. But it should solve your problem of not having to update the tutorial and the code every time.

Your suggestions looks very nice to me! But when I try to apply it, I get `WARNING: invalid signature for automodule`. The files that I want to parse are only scripts, do you know what command might do apply for them? — mindm49907, Jun 24 '15 at 07:01
Could you check if this solution solves your issue: http://stackoverflow.com/questions/13135120/python-how-i-can-define-in-sphinx-which-rst-files-and-directories-should-be-us — Subbdue, Jun 26 '15 at 06:02

Include a commented Python script into a Sphinx-generated documentation

1 Answers1