6.2. Setup Document Commands

The package setupdocx provides the creation, installation, and packaging of extended documentation. The provided tools offer a workflow for the local creation and installation during the authoring of the documents as well as the continous documentation during the software development process. The distribution for the remote installation is supported by the packaging command supporting a wide range of package types and archive formats. The commands are designed to be easily applicable by providing predefined configuration templates for altering the produced document view and type on the fly. Either automated, or by command line calls.

_images/document-flow.png

Figure: Documentation Workflow

The produced types of documents comprise

  • generated API documentation

  • generated API references

  • produced documents with optional integration of the API documentation and/or API references

  • produced arbitrary documents

6.2.1. build_docx

The command build_docx provides the creation of extended documentation based on a standard pattern. This includes optional the integrated creation of the API documentation and the API reference. The API documentation is hereby generated by a separate call which scans the code and creates documentation of a basic structure in printable style. In contars the optional API reference is based on a layout for the simplified navigation of large sets of structured interfaces in a JavaDoc style, thus mainly for HTML browsing. The two steps are tightly coupled with the processed document and provide the first basic integration. Thus these tools are bundled into one command, and could be optionally activated. The resulting document is a single bundled document ready for deployment.

While the API documentation could be created as standalone document simply by setting the option –rawdoc, the standalon API reference is available as a separate command, see build_apiref.

The supported toolsets for the first release are sphinx and epydoc.

CLI command

build_docx

API class

setupdocx.build_docx.BuildDocX

setup.cfg

build_docx

The current release supports:

  • Language: English

  • Document format: HTML, PDF, EPUB, MAN (for integrated APIref HTML only)

  • Document style: default based on ‘default’ of Python3

  • Sidebar entries: Fixed / skippy with some configuraion options, template derived from ‘classic’

  • Sphinx and Epydoc integration: ‘very basic’ fixed links by post-processing of HTML

  • Platform support - package creation: supported for bash, tested on Linux only

  • Platform support - distribution: any supported platform

Some project examples are:

6.2.2. dist_docx

The command dist_docx provides the creation distribution packages for documents. This includes the first release of the draft integration of sphinx and epydoc.

CLI command

dist_docx

API class

setupdocx.dist_docx.DistDocX

setup.cfg

dist_docx

The current release supports:

  • Language: English

  • Docuent format: HTML, PDF, EPUB, MAN

  • PAckage format: TAR, TARGZ, TGZ, XZ, ZIP

  • Platform support - package creation: supported for bash, tested on Linux only

  • Platform support - distribution: any supported platform

6.2.3. install_docx

The install_docx command installs the created document by build_docx from the build directory into the target directory. By default either within the project into doc, or into the users home directory.

6.2.4. build_apidoc

The command build_apidoc provides the standalone generation of the API standard documentation format. The standard call is embedded into build_docx by the option –apidoc.

The current release supports:

  • Language: English

  • Document format: HTML, PDF, EPUB, MAN (for integrated APIref HTML only)

  • Document style: default based on ‘default’ of Python3

  • Sidebar entries: Fixed / skippy with some configuraion options, template derived from ‘classic’

  • Sphinx and Epydoc integration: ‘very basic’ fixed links by post-processing of HTML

  • Platform support - package creation: supported for bash, tested on Linux only

  • Platform support - distribution: any supported platform

Some project examples are:

6.2.5. build_apiref

The command build_apiref provides the creation of the standalone API reference in JavaDoc style. The standard call is embedded into build_docx by the option –apiref.

The current release supports:

  • Language: English

  • Docuent format: HTML, PDF

  • Document style: default based on ‘default’ of epydoc

  • Sidebar entries: Fixed

  • Platform support - package creation: supported for bash, tested on Linux only

  • Platform support - distribution: any supported platform

Some project examples are: