Use Configuration Templates

Sphinx

  1. Select a Configuration Template

    Create your own from ground up, or select a provided theme and the appropriate configuration template. The following templates for Sphinx are contained in setupdocx.

  2. Define the Document Structure

    Define the appropriate document structure based on toctree, see [sphinxdoc] and [restdir]. Be aware, that document formats based on a single file behave differently than multi-file formats, though they obviously concatenate instead of linking by references. Thus the the different output formats require frequently configurations which contain the appropriate index.rst and more when required. See the contained subdirectory docsrc of the configuration, for the document creation including the setup.py refer to Create the Document.

  3. Copy the Configuration Template

    Copy the template directory in order to adapt your files, the structure, and the style. The directory is the later parameter –confdir of the call:

    python setup.py build_docx –confdir= <config-path>

  4. Adapt the Configuration Template

    The configuration template contains the required configuration data for the selected tools as well as for the independent autonomous representaion of the document, e.g. static data such as images and style sheets. The default is the Sphinx toolset [sphinxdoc].

    The configuration of sphinx provided by conf.py permits for multiple sections of different so called builders. This is e.g. html epub, latex for PDF, or man for manpages. Anyhow, due to additional restrictions, e.g. such as no image capabilities of man pages, or the different behaviour of single and multi page documents related in particular to the directives include, and toc, or references, it is advisable to distinguish each created document type by a separate set of configuration in it’s own directory. The directory contains the view parts as well as frequently required content patches. The most commonly required patch is here the main file index.rst, as well as the appropriate custom.css. Subdirectories such as customized _themes and _templates are supported too.

    The setupdocx in addition supports some sphinx extensions, in particular for the simplified size-adaptation of images including figures setupdocxSphinxExtImagewrap to the various output formats.

    The architecture of the setupdocx is based on multiple layers. The integration modules for setup.py support additional commands [distutils], while the actual used toolset is wrapped within a slim adaptation layer of scripts based on a command line interface. The provided default wrapper scripts are generic and may fit to all standard requirements. These are located within the installation directory of setupdocx. The search order for the actual executed script is

    1. confdir - –confdir

    2. docsrc - –docsource

    3. setupdocx - the installation directory

    Anyhow, when required the scripts could be easily modified or completely replaced. Either by persistent configuration, or call-by-call with teh parameters –build-apidoc, –build-apiref, or –build-doc. alternatively by a specific naming scheme for the build tools, e.g. –build-doc.

    The provided interface is based on envirnment variables, see ENVIRONMENT. The actual resulting environment parameters are displayed by the option global option ‘–verbose’, see also DOCX_VERBOSE. The current release contains bash scripts only, while additional based on PowerShell, and Python will follow soon.

    The required directory structure of the configuration template directory is for example in case of ReadTheDocs:

    <conf-template-name>
└── docsrc
    ├── conf.py             # this file must be edited
    ├── index.rst           # this file must be edited
    └── _static
        ├── custom.css
        ├── favicon.ico     # this file must be edited
        └── logo.png        # this file must be edited

    In case of included API reference, here based on epydoc:

    <conf-template-name>
└── docsrc
    ├── conf.py             # this file must be edited
    ├── index.rst           # this file must be edited
    └── _static
        ├── custom.css
        ├── epydoc.conf     # this file must be edited
        ├── epydoc.css      # this file must be edited
        ├── favicon.ico     # this file must be edited
        └── logo.png        # this file must be edited

    The same with optional custom call-scripts. Due to the pure environment based interface you can use whantever implementation language you want, as long as it is capable to read environment variables.

    <conf-template-name>
├── call_apidoc.ps1         # this is optional - implemented by 'PowerShell'
├── call_apiref.lua         # this is optional - implemented by 'Lua'
├── call_doc.py             # this is optional - implemented by 'Python'
└── docsrc
    ├── conf.py             # this file must be edited
    ├── index.rst           # this file must be edited
    └── _static
        ├── custom.css
        ├── epydoc.conf     # this file must be edited
        ├── epydoc.css      # this file must be edited
        ├── favicon.ico     # this file must be edited
        └── logo.png        # this file must be edited

    The complete content of the directory docsrc is copied into the directory.

    <build-dir>/apidoc/sphinx

    The files superpose the generated output by sphinx-apidoc called by first step of call_apidoc.sh. So check initially the created index.rst of sphinx-apidoc. The first step of the call of call_apidoc.sh could be suppressed by using an empty option –build-apidoc.

    python setup.py build_docx –build-apidoc=’’

    The other build steps could be deactivated the same way by –build-doc, while the build step of –apiref is optional and deactivated by default anyway.

    The required minimum modifications mainly comprise the name of the project, list of source directories, and eventually required extensions e.g. for Sphinx. The files are inline documented, though the modification should be easily done.

    See also Create Configuration Templates.

  5. Call ‘setup.py’

    Once the preparations are completed, the document should be created by the call:

    python setup.py build_docx –confdir=/your/configuration/path/

    The document is created by default in the directory:

    See also Create the Document, and EXAMPLES.

  6. Read the Document

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

    <build-dir>/doc/<docname>/index.html

For further steps refer to Install the Document, and Package the Document.

Epydoc - Standalone

available soon

Epydoc Embedded into Sphinx

available soon