Project documentation with Sphinx
Sphinx - Python Documentation Generator.
Step 1: install Sphinx
$ pip install Sphinx
Step 2: create folder in which documentation will be stored
$ mkdir docs $ cd docs
Step 3: initialize docs folder
$ sphinx-quickstart # answer to several questions # enter 'y' for 'Separate source and build directories'
Add to .gitignore:
docs/build
Step 4: modify Makefile, add target to run simple http server
Add to Makefile:
serve: make html && cd build/html/ && python -m SimpleHTTPServer 8001
Check that all works fine:
$ make serve # Open http://127.0.0.1:8001 in browser.
Step 5: edit source files
index.rst:
.. myproject documentation master file Welcome to myproject's documentation! ===================================== Contents: .. toctree:: :maxdepth: 2 init.rst usage.rst
init.rst:
.. myproject init Init ==== - ``virtualen .env --no-site-packages`` - ``source .env/bin/activate`` - ``pip install -r requirements.txt`` - ``cp settings_local.py.default settings_local.py`` - ``make syncdb`` - ``make run``
usage.rst:
.. myproject usage Usage ===== Some usage info. .. code-block:: bash make run `Simple link <http://sphinx-doc.org>`__
Try autodoc extension:
.. automodule:: io :members:
If You use django, add next lines to conf.py:
sys.path.insert(0, os.path.relpath('../../../myapp')) os.environ['DJANGO_SETTINGS_MODULE'] = 'myapp.settings'
Links:
Licensed under CC BY-SA 3.0