You will need sphinx to build the documentation. You can install it via pip:
pip install sphinx
The documentation looks better with the following package installed, however it is not requried:
pip install sphinx-better-theme
Once you have sphinx installed, you can build the documentation by running the following command from this directory:
sphinx-build source html
The second argument of the above command is the output directory. In other words this will generate the documentation into the "html" directory. If you wish to put it somewhere else you may supply a different path. Once the build completes you can point your web browser at the output directory you supplied and inspect the result.
Documentation is written using Sphinx. You must have Sphinx installed to build the documentation.
You can put python files in source/examples which can be referenced as examples from within the documentation/tutorials.
To make a named tag within an example python file, use a line of the
form # <tag_name>
to begin the tag (qwhere
tag_nameis replaced with the name of the tag) and a line of the form
# </tag_name>` to
end the tag. Tags do not have to be properly nested.
Upon build, tags will be preprocessed into new source files in the
source/tags directory. If the example file was called
source/examples/example1.py and contained the tags hello
, world
,
and python
, the files in the tags directory after preprocessing
would be source/tags/example1.py, source/tags/example1.py.hello.py,
source/tags/example1.py.world.py, and
source/tags/example1.py.python.py
NOTE: Files in source/tags are automatically generated and should never be editted directly.
To show the source of one of the tags files in a documentation file (.rst), use the syntax:
.. literalinclude:: ../tags/example1.py.hello.py
(with the path replaced appropriately).
Example:
source/examples/test.py:
# hello
# <tag3>
# <tag1>
# A comment
print "Hello world!"
# </tag1>
# <tag2>
# Another comment
print "hello world2!"
# </tag3>
# </tag2>