6

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!

4
  • 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, 2015 at 7: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 1, 2015 at 7: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 2, 2015 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: stackoverflow.com/q/30780334/407651.
    – mzjn
    Jul 2, 2015 at 18:31

1 Answer 1

1

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.

2
  • 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, 2015 at 7:01
  • Could you check if this solution solves your issue: stackoverflow.com/questions/13135120/…
    – Subbdue
    Jun 26, 2015 at 6:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.