3. Blueprint

The modern landscapes of information infrastructures are commonly designed and organized as stacks of heterogeneous runtime environments with comon frameworks. This frequently requires the installation of specific components for various platforms, including the generation of adapted packages, extended documentation, and the automation of distributed large-scale tests. The setupdocxs extends the setuptools for the required commands and options.

Figure: SetupDocX Integration

The package setupdocx provides the logical functions

Figure: SetupDocX functions apidoc and apiref

• build_docx

  • doc - Create documentation composed by edited reST modules and optional documentation generated from the code.

  • apidoc - Create documentation composed by edited reST modules and optional extracted inline documentation generated from the code.

• build_apiref

  • apiref - Create optional API reference by automated code analysis extended by optional inline documentation.

• dist_docx

  • create archives and distribution packages

• install_docx

  • install locally from source-build or distribution packages

The current implemented components are:

function	command	wrapper	builder
doc	build_docx –apidoc=’’	call_doc.sh	sphinx-build(1)
apidoc	build_docx	call_apidoc.sh	sphinx-build(1) + sphinx-apidoc(2)
apidoc	build_docx option “–apiref”	call_apidoc.sh + call_apiref.sh	sphinx-build(1) + sphinx-apidoc(2) + epydoc(3)
apiref	build_apiref	call_apiref.sh	epydoc(3)

(1): see [sphinx], [sphinx-build] - calls by default ‘build_doc’, “–apidoc=’’” deactivates the ‘build_apidoc’ call

(2): see [sphinx-apidoc]

(3): see [epydoc], requires for some syntax elements of Python3 some patches which will be publicly available soon

A widespread of commonly required themes and formats for the automation of internal and external publishing is contained by prepared configuration templates, additonal are available. Custom themes and templates could be easily added. The automation of open publication on various local and remote sites - e.g. local filesystem, local servers, github-pages, ReadTheDocs.org, SourceForge.io - is available by the distribution command install_docx.

The current extension commands provide the complete flow of document creation, packaging for distribution, and the installation.

Figure: Basic Documentation Workflow more…

• Document creation, packaging, distribution, and installation with sphinx and epdydoc integration:

  python setup.py build_docx        # compiles documents
  python setup.py build_apiref      # compiles documents
  python setup.py dist_docx         # creates document distribution packages
  python setup.py install_docx      # installs local from build directory

The processed programming languages, document types, and presentation styles could be easily adapted to a variety of predefined templates, and/or custom made designs. The customization provides for configurations, builder for various languages and document types, and presentation styles. The directory structure is the same for the the provided templates as required for user defined custom setups.

Figure: Standard and custom template directories.