.. _SETUPLIB_COMMANDS:


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. 

.. only:: singlehtml

   .. container:: figabstract
   
      .. figurewrap:: _static/document-flow.png
         :width-latex: 450
         :width: 550
         :target-html: _static/document-flow.png
         :align: center
         
      Figure: Documentation Workflow


.. only:: not singlehtml

   .. figurewrap:: _static/document-flow.png
      :width-latex: 450
      :width: 550
      :target-html: _static/document-flow.png
      :align: center
      
      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

.. _SETUP_BUILD_DOCX:

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
:ref:`--rawdoc <setupdocxbuild_OPTIONS_rawdoc>`, the standalon API reference is available as a
separate command, see :ref:`build_apiref <SETUP_BUILD_APIREF>`.

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

   .. raw:: html
   
      <div class="indextab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-------------+----------------------------------------------------------------------------------+
   | CLI command | :ref:`build_docx <setupdocxCOMMANDS_build_docx>`                                 |
   +-------------+----------------------------------------------------------------------------------+
   | API class   | `setupdocx.build_docx.BuildDocX <_modules/setupdocx/build_docx.html#BuildDocX>`_ |
   +-------------+----------------------------------------------------------------------------------+
   | setup.cfg   | :ref:`build_docx <setupCONF_build_docx>`                                         |
   +-------------+----------------------------------------------------------------------------------+

   .. raw:: html
      
      </div>
      </div>
      </div>


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 <install.html#>`_

Some project examples are:

* ePyUnit - [EPYUNIT]_ 
* filesysobjects - [FILESYSOBJECTS]_ 
* jsondata - [JSONDATA]_
* platformids - OS Type and Distribution IDs of System Platforms - [platformids]_
* platformids - [platformids]_ 
* pysourceinfo - [PYSOURCEINFO]_ 
* pythonids - Python Interpreter and Compiler IDs - [pythonids]_ 
* syscalls - [SYSCALLS]_
* etc. ...


.. _SETUP_DIST_DOCX:

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*. 

   .. raw:: html
   
      <div class="indextab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-------------+------------------------------------------------------------------------------+
   | CLI command | :ref:`dist_docx <setupdocxCOMMANDS_dist_docx>`                               |
   +-------------+------------------------------------------------------------------------------+
   | API class   | `setupdocx.dist_docx.DistDocX <_modules/setupdocx/dist_docx.html#DistDocX>`_ |
   +-------------+------------------------------------------------------------------------------+
   | setup.cfg   | :ref:`dist_docx <setupCONF_dist_docx>`                                       |
   +-------------+------------------------------------------------------------------------------+

   .. raw:: html
      
      </div>
      </div>
      </div>

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 <install.html#>`_

.. _SETUP_INSTALL_DOCX:

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.

   .. raw:: html
   
      <div class="indextab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-------------+------------------------------------------------------------------------------------------+
   | CLI command | :ref:`install_docx <setupdocxCOMMANDS_install_docx>`                                     |
   +-------------+------------------------------------------------------------------------------------------+
   | API class   | `setupdocx.install_docx.InstallDocX <_modules/setupdocx/install_docx.html#InstallDocX>`_ |
   +-------------+------------------------------------------------------------------------------------------+
   | setup.cfg   | :ref:`install_docx <setupCONF_install_docx>`                                             |
   +-------------+------------------------------------------------------------------------------------------+

   .. raw:: html
      
      </div>
      </div>
      </div>
      
           
.. _SETUP_BUILD_APIDOC:

build_apidoc
------------
The command *build_apidoc* provides the standalone generation of the API standard documentation format.
The standard call is embedded into :ref:`build_docx <SETUP_BUILD_DOCX>` by the option
:ref:`--apidoc <setupdocxbuild_OPTIONS_apidoc>`.



   .. raw:: html
   
      <div class="indextab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-------------+--------------------------------------------------------------------------------------------+
   | CLI command | :ref:`build_apidoc <setupdocxCOMMANDS_build_apidoc>`                                       |
   +-------------+--------------------------------------------------------------------------------------------+
   | API class   | `setupdocx.build_apidoc.BuildApidocX <_modules/setupdocx/build_apidoc.html#BuildApidocX>`_ |
   +-------------+--------------------------------------------------------------------------------------------+
   | setup.cfg   | :ref:`build_apidoc <setupCONF_build_apidoc>`                                               |
   +-------------+--------------------------------------------------------------------------------------------+

   .. raw:: html
      
      </div>
      </div>
      </div>


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 <install.html#>`_

Some project examples are:

* ePyUnit - [EPYUNIT]_ 
* filesysobjects - [FILESYSOBJECTS]_ 
* jsondata - [JSONDATA]_
* platformids - OS Type and Distribution IDs of System Platforms - [platformids]_
* pysourceinfo - [PYSOURCEINFO]_ 
* pythonids - Python Interpreter and Compiler IDs - [pythonids]_ 
* syscalls - [SYSCALLS]_
* etc. ...


.. _SETUP_BUILD_APIREF:

build_apiref
------------
The command *build_apiref* provides the creation of the standalone API reference in *JavaDoc* style.
The standard call is embedded into :ref:`build_docx <SETUP_BUILD_DOCX>` by the option
:ref:`--apiref <setupdocxbuild_OPTIONS_apiref>`.

   .. raw:: html
   
      <div class="indextab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-------------+--------------------------------------------------------------------------------------------+
   | CLI command | :ref:`build_apiref <setupdocxCOMMANDS_build_apiref>`                                       |
   +-------------+--------------------------------------------------------------------------------------------+
   | API class   | `setupdocx.build_apiref.BuildApirefX <_modules/setupdocx/build_apiref.html#BuildApirefX>`_ |
   +-------------+--------------------------------------------------------------------------------------------+
   | setup.cfg   | :ref:`build_apiref <setupCONF_build_apiref>`                                               |
   +-------------+--------------------------------------------------------------------------------------------+

   .. raw:: html
      
      </div>
      </div>
      </div>


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 <install.html#>`_

Some project examples are:

* ePyUnit - [EPYUNIT]_ 
* filesysobjects - [FILESYSOBJECTS]_ 
* jsondata - [JSONDATA]_
* platformids - OS Type and Distribution IDs of System Platforms - [platformids]_
* platformids - [platformids]_ 
* pysourceinfo - [PYSOURCEINFO]_ 
* pythonids - Python Interpreter and Compiler IDs - [pythonids]_ 
* syscalls - [SYSCALLS]_
* etc. ...