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