Create the Document

Sphinx

  1. Define the Document Structure

    Define the document structure based on toctree, see [sphinxdoc] and [restdir].

  2. Write the ‘setup.py’

    Write a setup with imported setupdocx classes, for a complete example refer to Source.

    1
2
3
4
5
6
7
    #
# setup extension modules
#
from setupdocx import usage, sed

# documents
from setupdocx.build_docx import BuildDocX

    Add a custom class:

    1
2
3
4
5
6
7
    class build_docx(BuildDocX):
    """Defines additional text processing.
    """

    def __init__(self, *args, **kargs):
        BuildDocX.__init__(self, *args, **kargs)
        self.name = 'setupdocx'

    Integrate into distutils [distutils]:

    1
2
3
4
    setup(
    cmdclass={
        'build_docx': build_docx,
    },

  3. Create the Configuration

    Create a configuration directory, e.g. by copying and adapting one of the provided templates. The provided templates should work out of the box on a production platform based on Linux - they did at the time of writing. Refer to the sections for a pre-view.

  4. Call the ‘setup.py’

    Create teh document:

    python setup.py build_docx --conf-dir=/your/configuration/path/

    The document is created by default in the directory:

    build/doc/<docname>

  5. Read the Document

    In case of the document type html this contains by default the main page:

    build/doc/<docname>/index.html

See also EXAMPLES.

Epydoc

available soon