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!
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 useliteralinclude
to include the verbatim contents of the script file in the documentation.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.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.