Project documentation with Sphinx

Sphinx - Python Documentation Generator

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