4. Command Line Interface¶

The package setupdocx provides the following extensions for the standard command line interface of setup.py from the setuptools / distutils. See EXAMPLES for required integration steps, check integration with:

python setup.py –help-commands

You should see the extra commands “build_docx”, “dist_docx”, and “install_docx”.

setup.py extension commands:

build_docx

Generate API specification, and create documents. Optional combined with apidoc, and apiref.

build_apidoc

Generate API specification only.

build_apiref

Generate Javadoc style API specification.

dist_docx

Package documents for distribution.

install_docx

Install documents from sources.

setup.py common global options:

–sdk

Extends the dependencies for development utilities.

–no-install-requires

Deactivates pre-requisites.

–offline

Deactivates PyPi access.

–help-setupdocx

Displays help for setupdocx.

4.1. SYNOPSIS¶

setup.py [Global-OPTIONS] [COMMANDS-with-context-OPTIONS]

4.2. OPTIONS¶

4.2.1. –sdk¶

Supports a separate dependency list for the build and packaging environment. The following informal convention has to be implemented within the file setup.py.

__sdk = False
"""Set by the option "--sdk". Controls the installation environment."""

if '--sdk' in sys.argv:
    _sdk = True
    sys.argv.remove('--sdk')


_packages_sdk = find_packages(include=['setupdocx'] )  # your development packages
"""Python packages to be installed."""


if __sdk: # pragma: no cover
    try:
        import sphinx_rtd_theme  # @UnusedImport
    except:
        sys.stderr.write("WARNING: Cannot import package 'sphinx_rtd_theme', cannot create local 'ReadTheDocs' style.")

    _install_requires.extend(
        [
            'sphinx >= 1.4',
            'epydoc >= 3.0',
        ]
    )

    _packages = _packages_sdk

For an example refer to setup.py of setupdocx.

4.2.2. –no-install-requires¶

Suppresses installation dependency checks, requires appropriate PYTHONPATH. The following informal convention has to be implemented within the file setup.py.

__no_install_requires = False

if '--no-install-requires' in sys.argv:
    __no_install_requires = True
    sys.argv.remove('--no-install-requires')


if __no_install_requires:
    print("#")
    print("# Changed to offline mode, ignore install dependencies completely.")
    print("# Requires appropriate PYTHONPATH.")
    print("# Ignored dependencies are:")
    print("#")
    for ir in _install_requires:
        print("#   "+str(ir))
    print("#")
    _install_requires=[]

For an example refer to setup.py of setupdocx.

4.2.3. –offline¶

Sets online dependencies to offline, or ignores online dependencies. The following informal convention has to be implemented within the file setup.py.

__offline = False

if '--offline' in sys.argv:
    __offline = True
    __no_install_requires = True
    sys.argv.remove('--offline')

For an example refer to setup.py of setupdocx.

4.2.4. –help-commands¶

The option ‘–help-commands’ itself is not part of the setupdocx, but it lists all successfull integrated extension commands. Thus the current extension commands has to be visible for validation.

4.2.5. –help-setupdocx¶

Special help for setupdocx.

For an example refer to setup.py of setupdocx.

4.3. COMMANDS¶

The commands could be combined within one call and are than processed from-left-to-right. But be aware that each command is a separate module, thus only knows it’s own options, which are the right-hand side options util the following next command. The context options for each command has to be provided separately. For example the change of the document e.g. by –name, or –docname, requires the appropriate parameter for each following command.

build_docx [build_docx-options]

create documents

build_apidoc [build_apidoc-options]

create API reference only

build_apiref [build_apiref-options]

create javadoc style API reference

dist_docx [dist_docx-options]

package documents

install_docx [install_docx-options]

install documents

4.3.1. build_docx¶

Creates Sphinx based documentation with optional embedded javadoc-style API reference by epydoc, html only. The command calls for the creation of the sphinx documents customizable scripts - see –build-apidoc , –build-doc, and –build-apiref - and passes the parameters as environment variables, see ENVIRONMENT.

4.3.1.1. –apidoc¶

Enables the creation call for the API documentation.
--apidoc

# default := '' # off
Sets the environment variable DOCX_APIDOC to the value ‘1’ when active.

4.3.1.2. –apiref¶

Enables the creation of the API reference.
--apiref

# default := '' # off
Sets the environment variable DOCX_APIREF to the value ‘1’ when active.

4.3.1.3. –break-on-err¶

Exits the build process on first error.
--break-on-error

# default := False
Sets the environment variable DOCX_BREAKONERR to the value ‘1’ when active.

4.3.1.4. –build-apiref=¶

Sets the build script for the apiref.
--apiref=(
    <path-to-script>    # calls the script
)

# default := <confdir>/call_apiref.sh
In case the provided value is a call name only the following locations are searched.

current configuration directory

document source for subdirectory ‘conf’

the ‘conf’ directory within the package setupdocx

If the parameter is not provided and not present in setup.conf, the default resolution is:

the default value from the class member docx_defaults

call_ref from current configuration directory

call_ref from document source for subdirectory ‘conf’

call_ref from the ‘conf’ directory within the package setupdocx

The called final tool is currently by default epydoc.
setup.py build_docx --apiref --build-apiref=<confdir>/call_apiref.sh
The current release supports by default bash scripts, this could be varied as required, e.g. by a DOS batch script, or a PowerShell script, or simply by a Python script.

See also Call Environment.

4.3.1.5. –build-apidoc=¶

Sets the called build-apidoc for document creation.
--build-apidoc=(
    <path-to-script>    # calls the script
    | sphinx-apidoc     # calls <confdir>/call_sphinx_apidoc.sh
    | ''                # the build stage is suppressed
)

# default := <confdir>/call_apidoc.sh
In case the provided value is a call name only the following locations are searched.

current configuration directory

document source for subdirectory ‘conf’

the ‘conf’ directory within the package setupdocx

If the parameter is not provided and not present in setup.conf, the default resolution is:

the default value from the class member docx_defaults

call_apidoc from current configuration directory

call_apidoc from document source for subdirectory ‘conf’

call_apidoc from the ‘conf’ directory within the package setupdocx

The called final tool is currently by default sphinx-apidoc.
setup.py build_docx --build-apidoc=<confdir>/call_apidoc.sh
The current release supports by default bash scripts, this could be varied as required, e.g. by a DOS batch script, or a PowerShell script, or simply by a Python script.

See also Call Environment.

4.3.1.6. –build-dir=¶

The base directory of the build directory tree.
--build-dir=(
    <path-to-build-root>    # sets the build root directory
)

# default := build/
The resulting actual build directory:
build/apidoc/sphinx
This directory is used as temporary build directory for all calls of the same build-dir. Sets the environment variable DOCX_BUILDDIR.

4.3.1.7. –build-doc=¶

Sets the called build-doc for document creation.
--build-doc=(
    <path-to-script>    | calls the script
    | sphinx            # calls <confdir>/call_sphinx.sh
    | ''                | the build stage is suppressed
)

# default := <confdir>/call_doc.sh
In case the provided value is a call name only the following locations are searched.

current configuration directory

document source for subdirectory ‘conf’

the ‘conf’ directory within the package setupdocx

If the parameter is not provided and not present in setup.conf, the default resolution is:

the default value from the class member docx_defaults

call_doc from current configuration directory

call_doc from document source for subdirectory ‘conf’

call_doc from the ‘conf’ directory within the package setupdocx

The called final tool is currently by default sphinx-build, which is called by the created Makefile with the option html.
setup.py build_docx --build-doc=<confdir>/call_doc.sh

# default := <confdir>/call_doc.sh
The current release supports by default bash scripts, this could be varied as required, e.g. by a DOS batch script, or a PowerShell script.

See also Call Environment.

4.3.1.8. –build-reldir=¶

The relative directory of the build directory tree.
--build-reldir=(
    <relative-path-to-build-dir>    # sets the build subdirectory
)

# default := apidoc/sphinx
The resulting actual build directory:
build/apidoc/sphinx
This directory is used as temporary build directory for all calls of the same build-dir. Sets the environment variable DOCX_BUILDRELDIR.

4.3.1.9. –build-proc=¶

The build procesor.

build-proc := (
       sphinx
     | sphinx-build
     | sphinx-apidoc
     | epydoc
     | ...
)

# default := sphinx == sphinx-build

The build processor sets the following defaults for the build calls.

default

build-doc

call_doc.sh (1)

build-apidoc

call_apidoc.sh (2)

build-apiref (4)

call_apiref.sh (3)

curently the same

curently the same

curently the same

called when option –apiref is present

4.3.1.10. –builder=¶

The builder, which includes all tools of the specific software package called the builder. The builder may contain one or more build-processors, e.g. sphinx-build, see also –build-proc.

Note

Not all are available for the initial relase.

builder := (
       sphinx
     | epydoc
     | docbook
     | doxygen
     | latex
     | mkdocs
     | pandoc
     | perldoc
     | texinfo
     | texinfo
     | txt2tags
)

# default := sphinx

Sets the environment variable DOCX_BUILDER. The builde sets the following defaults for the build calls, and eventually the document type parameters when required.

default

build-doc

call_doc.sh (1)

build-apidoc

call_apidoc.sh (2)

build-apiref (4)

call_apiref.sh (3)

curently the same

curently the same

curently the same

called when option –apiref is present

4.3.1.11. –cap¶

A comma separated list of or a single capabilities file. In case of a list each will be superporsed successively. The default loads the file in the orginal builder directory only. Non existing files raise an exception.

cap := <capability-file-path> [',' <cap>]
capability-file-path := <builder-path> <ossep> <capability-file>
builder-path :=  "full path prefix to capabilities file abs or rel"
capability-file :=(
     capabilities.json
   | capabilities.xml
   | capabilities.yaml
)
ossep := "OS path separator"

Note

This is an advanced option foreseen for development and test, thus should not applied regularly. It is strongly recommended to use the default contained in the builder subdirectory.

4.3.1.12. –clean¶

Cleans the output of the called external tool.

4.3.1.13. –clean-all¶

Cleans the build directories ‘apidoc’, and ‘apiref’.

4.3.1.14. –config-path=¶

The configuration directory. The directory contains the production and runtime data for configuration, style setup, the theme, etc.. The following figure depicts an example including the directories _build, _static, _templates, and _themes. These produce a compatible directory structure to sphinx-apidoc with the provided structural compatible build utilities make.bat and Makefile. The latter are adapted to the call interface based on the setupdocx environment variables - see ENVIRONMENT.

The project setupdocx for example does not utilize sphinx-apidoc at all.
rtd
└── docsrc
    ├── conf.py           # required for doc / sphinx-build withouth sphinx-apidoc
    │                     # else optional
    ├── epydoc.conf       # required for apiref/epydoc
    ├── index.rst         # opt.
    ├── make_docx.bat     # opt. supports more 'targets'
    ├── Makefile_docx     # opt. supports more targets
    ├── _build
    ├── _static
    │   ├── custom.css    # opt.
    │   ├── epydoc.css    # opt.
    │   ├── favicon.ico   # opt. rec. size 32x32
    │   └── logo.png      # opt. rec. size 64x64
    ├── _templates
    └── _themes
Including optional creation scripts customized for the specific document.
config-path := (
   <path-to-configuration-directory>
   | <confname>
)

# default := setupdocx/conf/<build-proc>/default/
This also contains the logo and the favicon. The expected default contents are:

file

content

remarks

call_doc.sh

customized create command

see Call Environment

call_apidoc.sh

customized sphinx-apidoc

see Call Environment

call_apiref.sh

customized API reference

see Call Environment

conf.py

Sphinx configuration file

The current version uses Sphinx, this may change

epydoc.css

epydoc style sheet

The current version uses Epydoc, this may change

epydoc.conf

epydoc configuration

The current version uses Epydoc, this may change

logo.png

used logo as PNG, recommended size 64x64

Copied into <build-directory>/_static

favicon.ico

favicon as ICO, recommended size 32x32

Copied into <build-directory>/_static

The following optional subdirectories are copied into the build directory when present:

directory

content

remarks

_themes

customized sphinx-themes

copied to <build-directory>/_themes

_templates

customized sphinx-templates

copied to <build-directory>/_templates

_static

arbitrary data

content copied into <build-directory>/_static

Sets the environment variable DOCX_CONFDIR.

4.3.1.15. –copyright=¶

A fixed text as copyright notice. The text is used literally, the default is:

(C) <year> <author>

4.3.1.16. –debug¶

Raises the debug flag by ‘1’.

Sets the incremented environment variable DOCX_DEBUG.

4.3.1.17. –docname=¶

The name of the created document. In case of the document type html this is the directory name. This could be different from the –name, e.g. in order to create the same document based on different themes.
docname := <name-of-file-or-directory>

# default := self.name
Sets the environment variable DOCX_DOCNAME.

4.3.1.18. –docsource=¶

Set the directory of the document sources.

default := docsrc/

For example:
setup.py build_docx --docsource=docsrc/
Sets the environment variable DOCX_DOCSRC.

4.3.1.19. –doctemplate=¶

Set the template for the document. The template is a subdirectory within the configuration directory of the builder (see –builder). The template subdirectory contains the configuration templates of the provided document types (see –doctemplate). The current present list of templates within the serach path (see –config-path) is available by the options –list-templates and –list-templates-std. For example:

.. parsed-literal::

   (3.8.0) [acue@lap001 setupdocx]$ python setup.py build_docx --list-templates-std

   running build_docx

   available builder templates for: epydoc - setupdocx.config.epydoc
             embedded/sphinx/default                  - html
             embedded/sphinx/rtd/iframe               - html
             embedded/sphinx/white-green/iframe       - html
             standalone                               - html

   available builder templates for: sphinx - setupdocx.config.sphinx
             agogo                                    - html
             alabaster                                - html
             bizstyle                                 - html
             bootstrap                                - html
             default                                  - html
             default_                                 - html
             guzzle                                   - html
             nature                                   - html
             pydoc2                                   - html
             pydoc3                                   - html
             rtd                                      - epub
             rtd                                      - html
             rtd                                      - man
             rtd                                      - pdf
             rtd                                      - singlehtml
             rtd-github                               - html
             rtd-readthedocs                          - html
             sphinxdoc                                - html
             traditional                              - html

   (3.8.0) [acue@lap001 setupdocx]$

For example:

setup.py build_docx --doctemplate=

Sets the environment variable DOCX_DOCTEMPLATE.

4.3.1.20. –doctype=¶

Set the format type of the created documentation. The supported types conssit of the pimary and the secondary format types. The primary format types are supported for all processing tools, where possible. These values are mapped as required to specific call parameters within the call wrapper e.g. call_doc.sh. The secondary format types are specific to the actuall used processing tool, thus are not permitted in all call contexts.

The build_docx supports a specific subset of the caled tools. Thus in some cases the processing tools has to be executed explicitly. This is supported by the dynamic created environment scripts for console usage, see persistent environment.
docname := (

   # primary types
     'html'            # directory containing the document
   | 'singlehtml'      # directory containing the document with one 'html' file
   | 'epub'            # a single file
   | 'man'             # directory containing multiple documents
   | 'mangz'           # directory containing multiple compressed documents
   | 'pdf'             # a single file

   # secondary types
   | 'latex'           # a single file
   | 'latexpdf'        # a single file
   | 'latexpdfja'      # a single file

   | 'devhelp'         # directory containing the document
   | 'htmlhelp'        # directory containing the document
   | 'qthelp'          # directory containing the document
)

# default := html
For example:
setup.py build_docx --doctype=html
Sets the environment variable DOCX_DOCTYPE.

4.3.1.21. –indexsrc¶

The source file to be copied into the build directory with the target name “index.rst”.
indexsrc := <file-path-name-index-replacement>

# default := index.rst
For the current version this file simply replaces the output ‘index.rst’ of sphinx-apidoc. The user is responsible for the correct content.

For example
setup.py build_docx --indexsrc=docsrc/index_rtd.rst
for a special variant for sphinx_rtd_theme or the online Read-The0Docs. While the same directory contains also the generic default file “docsrc/index.rst” for other themes.

Sets the environment variable DOCX_INDEXSRC.

4.3.1.22. –quiet¶

Quiet flag, disables console output for informal displays.

Sets the environment variable DOCX_QUIET.

4.3.1.23. –rawdoc¶

Creates documentation based on the output of the generators apidoc only. Supresses the copy of the documents from the subdirectory docsrc including the index.rst. If you need a document still contains some minor modifications, define minal configuration template.

default := None

Sets the environment variable DOCX_RAWDOC.

4.3.1.24. –ref-conf=¶

Configuration file for the called apiref, see call_apiref.sh
setup.py build_docx --epydoc-conf=<file-path-name>

# default := dopcsrc/epydoc.conf

4.3.1.25. –list-templates=¶

Displays lists of provided configuration templates from multiple paths. Supports multiple display options for the format of the paths.

setup.py build_docx --list-templates=<parameters>

parameters := '"'
   + ['baselist=' <searchpath> [';'] ]
   +  ['display=' <display-format> [';'] ]
   '"'
searchpath :=  <path> [<sep> <searchpath>]
sep := os.pathsep
display-format := (
     None     # <template-name>
   | short    # <tool>.<template-name>
   | full     # as provided
   | abs      # absolute
   | rel      # relative
)

see also setupdocx.conf_list.

Example:

The following call lists multiple directories:

python setup.py build_docx \
    --list-templates="baselist=conf_docs:setupdocx/configurations;display=None;"

# wrapped for readability

4.3.1.26. –list-templates-std¶

Displays the list of provided configuration templates.

setup.py build_docx --list-templates-std

Example:

python setup.py build_docx --list-templates-std

The current list is:

available templates: mkdocs

available templates: sphinx
     agogo
     alabaster
     bizstyle
     default
     epub
     guzzle_sphinx_theme
     man
     nature
     pdf
     sphinx_bootstrap_theme
     sphinx_rtd_on_github
     sphinx_rtd_theme
     sphinxdoc
     traditional

4.3.1.27. –name=¶

The name of the package. This is used by default as the output name of the document, see also –docname.
setup.py build_docx --name=<package-name>

# default := <current-package-name> - self.name
Sets the environment variable DOCX_NAME.

4.3.1.28. –no-exec¶

Print only, do not execute

setup.py build_docx --no-exec

# default := False

4.3.1.29. –no-exec-max¶

Print only all calls in the workflow despite the final call of the external tools. This displays the resulting calls of the all levels.
setup.py dist_docx --no-exec-max
setup.py dist_docx -N

# default: False
Custom scripts have to comply to these convention.

See also –no-exec.

4.3.1.30. –set-release¶

Release to be set for the document. This is used literally.
setup.py build_docx --set-release=<arbitrary-string>
arbitrary-string := "probably not too long, and if possible ASCII only :-)"
Sets the environment variable DOCX_RELEASE.

4.3.1.31. –set-version¶

Version number to be set for the document. Requires digits and dots ‘.’ only:
setup.py build_docx --set-version=11.22.33
setup.py build_docx --set-version=11.22
setup.py build_docx --set-version=11
Normalizes to a 3-number version identifier:
11.22.33
11.22.0
11.0.0
Sets the environment variable DOCX_VERSION.

4.3.1.32. –srcdir=¶

The name of the directories containing the source code of the project. Either a single name, or a string containing semicolon separated list of paths, similar to DOS-search paths. This syntax permits seamless inclusions of URIs.
srcdir := <dir-name>[';'<srcdir>]

# default := <package-name>
For example:
setup.py build_docx --srcdir=<package-name>
Sets the environment variable DOCX_SRCDIR.

4.3.1.33. –verbose¶

Verbose flag for the local command context. Each repetition raises the level. The option –quiet resets the current counter to zero, while following –verbose flags continue to count than form zero on, see semantics of verbose and quiet.
setup.py build_docx --verbose -v --verbose -v
The behaviour is defined a bit special:

when a global option –verbose is set only, this is inherited by the local option

the local options replaces the global default

the option is normalized to 1 in combination with the flag –quiet

For additional details refer Howto Apply Verbose and Quiet.

4.3.1.34. –verbose-ext¶

Verbose flag passed transparently to the called external tools. The integer value defines the level. The value is combined with the current quiet mode, see semantics of verbose and quiet.
setup.py build_docx --verbose-ext=2
setup.py build_docx -x 2
For additional details refer Called Subcommands.

4.3.2. build_apidoc¶

Creates a document with contents from the extracted in-line documentation only. The command calls for the creation of the documents customizable scripts - –build-apidoc - and passes the parameters as environment variables, see ENVIRONMENT. For supported formats refer to –doctype=

4.3.2.1. –build-apidoc=¶

Sets the build script for the apidoc.
--apidoc=(
    <path-to-script>    # calls the script
)

# default := <config-path>/call_apidoc.sh
In case the provided value is a call name only the following locations are searched.

current configuration directory

document source for subdirectory ‘conf’

the ‘conf’ directory within the package setupdocx

If the parameter is not provided and not present in setup.conf, the default resolution is:

the default value from the class member docx_defaults

call_ref from current configuration directory

call_ref from document source for subdirectory ‘conf’

call_ref from the ‘conf’ directory within the package setupdocx

The called final tool is currently by default epydoc.
setup.py build_apidoc --apidoc --build-apidoc=<config-path>/call_apidoc.sh
The current release supports by default bash scripts, this could be varied as required, e.g. by a DOS batch script, or a PowerShell script, or simply by a Python script.

See also Call Environment.

4.3.2.2. –build-dir=¶

The base directory of the build directory tree.
--build-dir=(
    <path-to-build-root>    # sets the build root directory
)

# default := build/
The resulting actual build directory:
build/apidoc/sphinx
This directory is used as temporary build directory for all calls of the same build-dir. Sets the environment variable DOCX_BUILDDIR.

4.3.2.3. –clean¶

Cleans the output of the called external tool.

4.3.2.4. –config-path=¶

The configuration directory. The directory contains the production and runtime data for configuration and style setup. The following figure depicts an example.
apidoc_only
├── call_apidoc.sh        # optional custom script
├── epydoc.conf
└── docsrc
    ├── epydoc.css
    ├── favicon.ico
    └── logo.png
Including optional creation scripts customized for the specific document.
config-path := (
   <path-to-configuration-directory>
   | <confname>
)

# default := setupdocx/conf/<build-proc>/default/
This also contains the logo and the favicon. The expected default contents are:

file

content

remarks

call_apiref.sh

customized API reference

see Call Environment

epydoc.css

epydoc style sheet

The current version uses Epydoc, this may change

epydoc.conf

epydoc configuration

The current version uses Epydoc, this may change

logo.png

used logo as PNG, recommended size 64x64

Copied into <build-directory>

favicon.ico

favicon as ICO, recommended size 32x32

Copied into <build-directory>

Sets the environment variable DOCX_CONFDIR.

4.3.2.5. –docname=¶

The name of the created document. In case of the document type html this is the directory name. This could be different from the –name, e.g. in order to create the same document based on different themes.
docname := <name-of-file-or-directory>

# default := self.name
Sets the environment variable DOCX_DOCNAME.

4.3.2.6. –docsource=¶

Set the directory of the document sources.

default := docsrc/

For example:
setup.py apiref_docx --docsource=docsrc/
Sets the environment variable DOCX_DOCSRC.

4.3.2.7. –doctype=¶

Set the type of the created documentation.

docname := (
   # primary format types
     'html'
   | 'pdf'

   # secondary format types
   | 'auto'      # PDF
   | 'latexpdf'  # PDF
   | 'pdflatex'  # PDF

   | 'ps'
   | 'dvi'
   | 'latex'
   | 'tex'
)

# default := html

For example:

setup.py apiref_docx --doctype=html

Sets the environment variable DOCX_DOCTYPE.

4.3.2.8. –ref-conf=¶

Configuration file for the called apiref, see call_apiref.sh
setup.py apiref_docx --epydoc-conf=<file-path-name>

# default := dopcsrc/epydoc.conf

4.3.2.9. –name=¶

The name of the package. This is used by default as the output name of the document, see also –docname.
setup.py apiref_docx --name=<package-name>

# default := <current-package-name> - self.name
Sets the environment variable DOCX_NAME.

4.3.2.10. –no-exec¶

Print only, do not execute

setup.py apiref_docx --no-exec

# default := False

4.3.2.11. –set-release¶

Release to be set for the document. This is used literally.
setup.py apiref_docx --set-release=<arbitrary-string>
arbitrary-string := "probably not too long, and if possible ASCII only :-)"
Sets the environment variable DOCX_RELEASE.

4.3.2.12. –set-version¶

Version number to be set for the document. Requires digits and dots ‘.’ only:
setup.py apiref_docx --set-version=11.22.33
setup.py apiref_docx --set-version=11.22
setup.py apiref_docx --set-version=11
Normalizes to a 3-number version identifier:
11.22.33
11.22.0
11.0.0
Sets the environment variable DOCX_VERSION.

4.3.2.13. –srcdir=¶

The name of the directories containing the source code of the project. Either a single name, or a string containing semicolon separated list of paths, similar to DOS-search paths. This syntax permits seamless inclusions of URIs.
srcdir := <dir-name>[';'<srcdir>]

# default := <package-name>
For example:
setup.py apiref_docx --srcdir=<package-name>
Sets the environment variable DOCX_SRCDIR.

4.3.2.14. –verbose¶

Verbose flag for the local command context. Each repetition raises the level. The option –quiet resets the current counter to zero, while following –verbose flags continue to count than form zero on, see semantics of verbose and quiet.
setup.py install_docx --verbose -v --verbose -v
The behaviour is defined a bit special:

when a global option –verbose is set only, this is inherited by the local option

the local options replaces the global default

the option is normalized to 1 in combination with the flag –quiet

For additional details refer Howto Apply Verbose and Quiet.

4.3.2.15. –verbose-ext¶

Verbose flag passed transparently to the called external tools. The integer value defines the level. The value is combined with the current quiet mode, see semantics of verbose and quiet.
setup.py build_apidoc --verbose-ext=2
setup.py build_apidoc -x 2
For additional details refer Called Subcommands.

4.3.3. build_apiref¶

Creates Epydoc based standalone javadoc-style API reference. The command calls for the creation of the documents customizable scripts - –build-apiref - and passes the parameters as environment variables, see ENVIRONMENT. For supported formats refer to –doctype=

4.3.3.1. –build-apiref=¶

Sets the build script for the apiref.
--apiref=(
    <path-to-script>    # calls the script
)

# default := <config-path>/call_apiref.sh
In case the provided value is a call name only the following locations are searched.

current configuration directory

document source for subdirectory ‘conf’

the ‘conf’ directory within the package setupdocx

If the parameter is not provided and not present in setup.conf, the default resolution is:

the default value from the class member docx_defaults

call_ref from current configuration directory

call_ref from document source for subdirectory ‘conf’

call_ref from the ‘conf’ directory within the package setupdocx

The called final tool is currently by default epydoc.
setup.py build_docx --apiref --build-apiref=<config-path>/call_apiref.sh
The current release supports by default bash scripts, this could be varied as required, e.g. by a DOS batch script, or a PowerShell script, or simply by a Python script.

See also Call Environment.

4.3.3.2. –build-dir=¶

The base directory of the build directory tree.
--build-dir=(
    <path-to-build-root>    # sets the build root directory
)

# default := build/
The resulting actual build directory:
build/apidoc/sphinx
This directory is used as temporary build directory for all calls of the same build-dir. Sets the environment variable DOCX_BUILDDIR.

4.3.3.3. –clean¶

Cleans the output of the called external tool.

4.3.3.4. –config-path=¶

The configuration directory. The directory contains the production and runtime data for configuration and style setup. The following figure depicts an example.
apiref_only
├── call_apiref.sh        # optional custom script
├── epydoc.conf
└── docsrc
    ├── epydoc.css
    ├── favicon.ico
    └── logo.png
Including optional creation scripts customized for the specific document.
config-path := (
   <path-to-configuration-directory>
   | <confname>
)

# default := setupdocx/conf/<build-proc>/default/
This also contains the logo and the favicon. The expected default contents are:

file

content

remarks

call_apiref.sh

customized API reference

see Call Environment

epydoc.css

epydoc style sheet

The current version uses Epydoc, this may change

epydoc.conf

epydoc configuration

The current version uses Epydoc, this may change

logo.png

used logo as PNG, recommended size 64x64

Copied into <build-directory>

favicon.ico

favicon as ICO, recommended size 32x32

Copied into <build-directory>

Sets the environment variable DOCX_CONFDIR.

4.3.3.5. –docname=¶

The name of the created document. In case of the document type html this is the directory name. This could be different from the –name, e.g. in order to create the same document based on different themes.
docname := <name-of-file-or-directory>

# default := self.name
Sets the environment variable DOCX_DOCNAME.

4.3.3.6. –docsource=¶

Set the directory of the document sources.

default := docsrc/

For example:
setup.py apiref_docx --docsource=docsrc/
Sets the environment variable DOCX_DOCSRC.

4.3.3.7. –doctype=¶

Set the type of the created documentation.

docname := (
   # primary format types
     'html'
   | 'pdf'

   # secondary format types
   | 'auto'      # PDF
   | 'latexpdf'  # PDF
   | 'pdflatex'  # PDF

   | 'ps'
   | 'dvi'
   | 'latex'
   | 'tex'
)

# default := html

For example:

setup.py apiref_docx --doctype=html

Sets the environment variable DOCX_DOCTYPE.

4.3.3.8. –ref-conf=¶

Configuration file for the called apiref, see call_apiref.sh
setup.py apiref_docx --epydoc-conf=<file-path-name>

# default := dopcsrc/epydoc.conf

4.3.3.9. –name=¶

The name of the package. This is used by default as the output name of the document, see also –docname.
setup.py apiref_docx --name=<package-name>

# default := <current-package-name> - self.name
Sets the environment variable DOCX_NAME.

4.3.3.10. –no-exec¶

Print only, do not execute

setup.py apiref_docx --no-exec

# default := False

4.3.3.11. –set-release¶

Release to be set for the document. This is used literally.
setup.py apiref_docx --set-release=<arbitrary-string>
arbitrary-string := "probably not too long, and if possible ASCII only :-)"
Sets the environment variable DOCX_RELEASE.

4.3.3.12. –set-version¶

Version number to be set for the document. Requires digits and dots ‘.’ only:
setup.py apiref_docx --set-version=11.22.33
setup.py apiref_docx --set-version=11.22
setup.py apiref_docx --set-version=11
Normalizes to a 3-number version identifier:
11.22.33
11.22.0
11.0.0
Sets the environment variable DOCX_VERSION.

4.3.3.13. –srcdir=¶

The name of the directories containing the source code of the project. Either a single name, or a string containing semicolon separated list of paths, similar to DOS-search paths. This syntax permits seamless inclusions of URIs.
srcdir := <dir-name>[';'<srcdir>]

# default := <package-name>
For example:
setup.py apiref_docx --srcdir=<package-name>
Sets the environment variable DOCX_SRCDIR.

4.3.3.14. –verbose¶

Verbose flag for the local command context. Each repetition raises the level. The option –quiet resets the current counter to zero, while following –verbose flags continue to count than form zero on, see semantics of verbose and quiet.
setup.py install_docx --verbose -v --verbose -v
The behaviour is defined a bit special:

when a global option –verbose is set only, this is inherited by the local option

the local options replaces the global default

the option is normalized to 1 in combination with the flag –quiet

For additional details refer Howto Apply Verbose and Quiet.

4.3.3.15. –verbose-ext¶

Verbose flag passed transparently to the called external tools. The integer value defines the level. The value is combined with the current quiet mode, see semantics of verbose and quiet.
setup.py build_docx --verbose-ext=2
setup.py build_docx -x 2
For additional details refer Called Subcommands.

4.3.4. dist_docx¶

Creates a distribution package of the documentation. The naming convention is based on the common naming scheme of installation packages.

multi-file documents:

Multi-file documents consist of multiple files with a master file as the landing point. A typical example is the document type html.
```
unpackname = <name> + "-doc-" + <doctype> [ + "-" + <version>] [ + "-" + <release>] [ + "-" + <date>] [ + "-" + <platform>] + os.sep
```
single-file documents:

In case of a single file document the file is either contained in a directory, compressed at the top level without a container directory, or simply compressed by itself with gzip. The standard behaviour is to compress single file documents without a container directory. Thus these are decompressed by default into the same directory as the archive. This is the default behaviour for all archive type capable of archiving directories.

The case of compressed single files results in an archive for each contained file within the directory, which are extrated within the same directory. This is the behavior of the compression defined by gzip.
unpackname = <original-file-name-of-document>
The handling of the case with a containing directory has to be forced by the flag –forcedir. The resulting behaviour is the same as for multi-file documents where the file is contained within the unpack directory.
```
unpackname = <name> + "-doc-" + <doctype> [ + "-" + <version>] [ + "-" + <release>] [ + "-" + <date>] [ + "-" + <platform>]
```
multiple single-file documents:

Multiple single file documents bundled together in a shared directory. A typical example is man and mangz where multiple man pages are created for a single package. Same for pdf manals combined with separate howto and faq within a shared document directoy. These are by default handeled similar to documents consisting of multiple files, and are packed within a single unpack directory containing the original document files.
```
unpackname = <name> + "-doc-" + <doctype> [ + "-" + <version>] [ + "-" + <release>] [ + "-" + <date>] [ + "-" + <platform>] + os.sep
```

For example:

multi-file documents:

A single directory with multiple files, typical example is html, but also singlehtml, which has one html page, but still requires additional media such as images, scripts, and style sheets.

Input:

<original-file-name-of-document>/<file-parts>

Archive contents:

setupdocx-doc-html-1.3.5-alpha-2019.05.01.x86_64.<format>:<original-file-name-of-document>/<file-parts>
setupdocx-doc-html-1.3.5-alpha.x86_64.<format>:<original-file-name-of-document>/<file-parts>
setupdocx-doc-html-1.3.5.amd64.<format>:<original-file-name-of-document>/<file-parts>
setupdocx-doc-html-alpha.amd64.<format>:<original-file-name-of-document>/<file-parts>
setupdocx-doc-html.amd64.<format>:<original-file-name-of-document>/<file-parts>

Output:

<original-file-name-of-document>/<file-parts>

single-file documents and multiple single-file documents:

A single file as the resulting document, typical examples are pdf and epub.

Input:

<original-file-name-of-document>

Archive contents:

Default:

setupdocx-doc-html-1.3.5-alpha-2019.05.01.amd64.<format>:<original-file-name-of-document>
setupdocx-doc-html-1.3.5-alpha.amd64.<format>:<original-file-name-of-document>
setupdocx-doc-html-1.3.5.x86_64.<format>:<original-file-name-of-document>
setupdocx-doc-html-alpha.x86_64.<format>:<original-file-name-of-document>
setupdocx-doc-html.x86_64.<format>:<original-file-name-of-document>

With forced container directory:

setupdocx-doc-html-1.3.5-alpha-2019.05.01.arm7hl.<format>:<origial-container-directory>/<original-file-name-of-document>
setupdocx-doc-html-1.3.5-alpha.arm64.<format>:<origial-container-directory>/<original-file-name-of-document>
setupdocx-doc-html-1.3.5.armhfp.<format>:<origial-container-directory>/<original-file-name-of-document>
setupdocx-doc-html-alpha.i686.<format>:<origial-container-directory>/<original-file-name-of-document>
setupdocx-doc-html.x86.<format>:<origial-container-directory>/<original-file-name-of-document>

Output:

Default:
<original-file-name-of-document>
With forced container directory - –forcedir:
<origial-container-directory>/<original-file-name-of-document>

Note

The version and the release are optional. The release is a provided literal string which could replace version completely.

The version is extracted from the metadata of the package.

4.3.4.1. –append¶

Append files to existing archive. The default is to create new and replace the previous. Can be used to add new unpack-dir to an existing archive.
setup.py dist_docx --append

# default: False

4.3.4.2. –build-dir=¶

The location of the compiled document. The document has to be already created by the command build_docx.
setup.py dist_docx --build-dir=<processed-document>

# default 'build/'

4.3.4.3. –clean¶

Cleans the output of the created previous distribution.

4.3.4.4. –date¶

Adds the current date to the archive name:
setup.py dist_docx --date
The output format is:
date := YYYY.MM.DD

4.3.4.5. –debug¶

Debug level:

setup.py dist_docx --debug=3
setup.py dist_docx --debug=
setup.py dist_docx -d 3

4.3.4.6. –dist-dir=¶

Archive location for creation:

setup.py dist_docx --dist-dir=<output-location-for-archive>

# default 'dist/'

4.3.4.7. –doctype=¶

The document type to pack.
doctype := (
     'html'
   | 'epub'
   | 'man'
   | 'pdf'

   | 'latex'
   | 'latexpdf'
   | 'latexpdfja'
   | 'singlehtml'

   | 'devhelp'
   | 'htmlhelp'
   | 'qthelp'
)

# default 'html'
For example:
setup.py dist_docx --doctype='html'
The internally called subsystems such as sphinx may provide more formats, when required these has to be called by the interface of the subsystem.

4.3.4.8. –extra-suffixes=¶

Adds additional valid input suffixes for single file documents. Single file documents are validated by suffixes, e.g. ‘.pdf’ or ‘.epub’. The same in case of ‘doctype=man’, for each manpage the suffixes are checked as a single digit - ‘.[0-9]’. In case of ‘doctype=mangz’ checked as ‘.gz’. For additional non-digit suffixes extra suffixes are added to the validation list.
extra-suffixes := <valid-suffix> [, <extra-suffixes>]
valid-suffix := "any literal suffix with a leading dot - '.'"
For example:
setup.py dist_docx --dist-dir=<output-location-for-archive>

# default 'dist/'

4.3.4.9. –force¶

Force to processing by deactivating non-essential checks. Suppresses validation.

default: False

4.3.4.10. –forcedir¶

Force to pack all types by containing directories including single document types such as PDF. Else the types PDF, and EPUB are compressed without the containing directory.

default: False

4.3.4.11. –formats=¶

The archive types. A comma separated list of types of the created packages. Default is ‘zip’, see also ‘–help-formats’.

--formats := <arch-type> [',' <formats>]

arch-type := "see following table"

Current available types are:

option

suffix

remark

bzip2

.bz2

gzip

.gz

Applicable to single file documents only - pdf, epub, man, ps.

lzma

.lzma

Python3.3+. Python2.7 with backports.lzma [backlzma]

tar

.tar

targz

.tar.gz

tgz

.tgz

xz

.xz

Python3.3+. Python2.7 with backports.lzma [backlzma]

zip

.zip

4.3.4.12. –help-doctypes¶

Enumerates available document types.

4.3.4.13. –help-formats¶

Enumerates available distribution formats.

4.3.4.14. –name=¶

The name of the package

setup.py dist_docx --name=<package-name>

# default := <current-package-name>

4.3.4.15. –name-in=¶

The name of the input package

setup.py dist_docx --name-in=<package-name>

# default := self.name

4.3.4.16. –name-out=¶

The name of the package part of the output archive
setup.py dist_docx --name0out=<package-name>

# default := self.name

4.3.4.17. –no-exec¶

Print only, do not execute. This displays the resulting calls of the first level only.
setup.py dist_docx --no-exec
setup.py dist_docx -n

# default: False

4.3.4.18. –plat-name=¶

The optional name of the platform. The name could be an arbitrary string, even though it shold comply to the common labels. The name is be added to the archive name. Even though the document itself is platform independent, the contents may not.

4.3.4.19. –quiet=¶

Sets the quiet flag, for the special implementation in compliance of distutils see Howto Apply Verbose and Quiet.

4.3.4.20. –set-release=¶

A user provided release string. The string is added to the Version of created archive
setup.py dist_docx --set-version=<valid-version-string>

# default: <year>.<month>.<day>

4.3.4.21. –set-version¶

Version of created archive. Extracted from the packages metadata as provided by the call of ‘setup’ in ‘setup.py’.
setup.py dist_docx --set-version=<valid-version-string>

# default: <year>.<month>.<day>

4.3.4.22. –verbose¶

Verbose flag for the local command context. Each repetition raises the level. The option –quiet resets the current counter to zero, while following –verbose flags continue to count than form zero on, see semantics of verbose and quiet.
setup.py dist_docx --verbose -v --verbose -v
The behaviour is defined a bit special:

when a global option –verbose is set only, this is inherited by the local option

the local options replaces the global default

the option is normalized to 1 in combination with the flag –quiet

For additional details refer Howto Apply Verbose and Quiet.

4.3.5. install_docx¶

Install a local copy from the build directory of the previously build documents in accordance to PEP-370. When the build target has changed e.g. by –name, or –docname, than the appropriate name has to be provided for the install_docx too.

4.3.5.1. –build-dir=¶

The location of the compiled document. The document has to be already created by the command build_docx.
setup.py install_docx --build-dir=<source-directory>

# default: 'build'

4.3.5.2. –clean¶

Cleans the output of the created previous installation.

4.3.5.3. –debug¶

Debug flag.

setup.py install_docx --debug

4.3.5.4. –docname=¶

The name of the created document. In case of the document type html this is the directory name. This could be different from the –name, e.g. in order to create the same document based on different themes.
docname := <name-of-file-or-directory>

# default := self.name

4.3.5.5. –doctype=¶

Document type to install. The document type controls the actual target structure.

This varies in dependence of the type, so for example the man pages [man] are subdivided into sections, where the files are separated automatically by their section numbers. This places the files into the section structure in companion with other man pages. The section directories are created automatically when not yet present.

The behaviour could be forced to the installation of the named document package with the option –forcedir
doctype := (
     'html'
   | 'epub'
   | 'man'
   | 'pdf'

   | 'latex'
   | 'latexpdf'
   | 'latexpdfja'
   | 'singlehtml'

   | 'devhelp'
   | 'htmlhelp'
   | 'qthelp'
)

# default 'html'
With the call:
setup.py install_docx --doctype='html'

# default: html

4.3.5.6. –forcedir¶

Force to instal all types by containing directories including single document types such as pdf, and structured types like man pages. Else the types pdf, epub, and other single file documents are compressed without the containing directory, while the types man and mangz are by default installed into a man page section tree structure [man].

The flag changes the behaviour to the installation of the flat document directory of the package without the consideration of the man structure. In case of single documents these are stored with their directory prefix. Thus the documents are unpacked within their original directory.

The flag has no effect for multi-file documents of types like html and singlehtml.

default: False

4.3.5.7. –name=¶

Package name, changes ‘self.name’.
setup.py install_docx --name=<self-name>

# default: self.name

4.3.5.8. –no-exec¶

Print only, do not execute.
setup.py install_docx --no-exec

4.3.5.9. –target-dir¶

Installation target directory. The complete path for the location of the installed document, excluding the document name.
setup.py install_docx --target-dir=<target-directory>
Default is in user data, see also PEP-370. Either
~/.local/doc/en/html/man3/"+str(self.docname)
, or
%APPDATA%/doc/en/html/man3/"+str(self.docname)

4.3.5.10. –verbose¶

Verbose flag for the local command context. Each repetition raises the level. The option –quiet resets the current counter to zero, while following –verbose flags continue to count than form zero on, see semantics of verbose and quiet.
setup.py install_docx --verbose -v --verbose -v
The behaviour is defined a bit special:

when a global option –verbose is set only, this is inherited by the local option

the local options replaces the global default

the option is normalized to 1 in combination with the flag –quiet

For additional details refer Howto Apply Verbose and Quiet.

4.4. ENVIRONMENT¶

The command calls for the creation of the sphinx documents customizable scripts - see –build-apidoc , –build-doc, and –build-apiref - and passes the following environment variables as parameters.

The environment is passed to all commands. In addition two files were created for test and debugging purposes in order to use the command line tools and the make files from the console.

setenv.sh - sets and exports the environment variables, compatible to bash, ksh, sh, etc.
setenv.bat - sets and exports the environment variables, compatible to CMD.EXE

The environment variables are:

environment variable

corresponding option

default

DOCX_APIDOC

–apidoc

‘’

DOCX_APIREF

–apiref

‘’

DOCX_BUILDER

–builder

sphinx

DOCX_BUILDDIR

–build-dir

build/

DOCX_BUILDRELDIR

–build-reldir

apidoc/sphinx/

DOCX_CLEAN

–clean

False

DOCX_CONFDIR

–confdir

docsrc/conf/

DOCX_DEBUG

–debug

0

DOCX_DOCNAME

–docname

self.name (package-name)

DOCX_DOCSRC

–docsource

docsrc/

DOCX_DOCTYPE

–doctype

html

DOCX_EMBED

–

‘’

DOCX_INDEXSRC

–indexsrc

“index.rst”

DOCX_LIB

–

os.path.dirname(__file__)

DOCX_NAME

–name

self.name (package-name)

DOCX_NOEXEC

–no-exec

‘’

DOCX_QUIET

–quiet

0

DOCX_RAWDOC

–rawdoc

‘’

DOCX_RELEASE

–set-release

<YYYY-MM-DD>

DOCX_SRCDIR

–srcdir

self.name (package-name)

DOCX_DOCTEMPLATE

–doctemplate

‘default’

DOCX_VERBOSE

0

DOCX_VERBOSEX

–verbose-ext

0

DOCX_VERSION

–set-version

<setup.py>

4.4.1. DOCX_APIDOC¶

Enables the creation of the API documentation. Is set by the option –apidoc to ‘1’ when enabled. The default value is an empty string ‘’, for disabled.

4.4.2. DOCX_APIREF¶

Enables the creation of the API reference. Is set by the option –apiref to ‘1’ when enabled. The default value is an empty string ‘’, for disabled.

4.4.3. DOCX_BREAKONERR¶

Enables the immediate termination after an error. The default behaviour is to ignore. Is set by the option –break-on-err. The default value is ‘build/’, for the standard subdirectory.

4.4.4. DOCX_BUILDDIR¶

Sets the intermediate build directory. Is set by the option –build-dir. The default value is ‘build/’, for the standard subdirectory.

4.4.5. DOCX_BUILDER¶

Sets the intermediate builder package. Is set by the option –builder. The default value is ‘sphinx’, for the standard package.

4.4.6. DOCX_BUILDRELDIR¶

Sets the intermediate subdirectory of the build directory. Is set by the option –build-reldir. The default value is ‘apidoc/sphinx’, for the standard subdirectory.

4.4.7. DOCX_CLEAN¶

Sets the clean flag for the called wrapper. Cleans the output of the external tools.

4.4.8. DOCX_CONFDIR¶

Sets the configuration directory. Is set by the option –confdir. The default value is ‘docsrc/conf/’, for the standard source directory.

4.4.9. DOCX_DEBUG¶

Raises the debug state.

4.4.10. DOCX_DOCNAME¶

Sets the document name, this alters the default name set by DOCX_DOCNAME. Is set by the option –docname. The default value is ‘self.name(package-name)’, for the current package name as set in the setup.py by the derived classes from setup.py.

See also DOCX_NAME.

4.4.11. DOCX_DOCSRC¶

Sets the document source directory. Is set by the option –docsource. The default value is ‘docsrc/’, for the standard source directory.

4.4.12. DOCX_DOCTYPE¶

Sets the created document type. Is set by the option –doctype. The default value is ‘html’, for the standard format.

4.4.13. DOCX_EMBED¶

Sets the flag for the embedding of the subdocuments into the main document. When not set, the called subscipts should be aware to create a standalone document.

4.4.14. DOCX_INDEXSRC¶

Sets the index file. The index file is copied into the build directory and replaces the a file created by the production step call_apidoc.sh. Is set by the option –indexsrc. The default value is ‘docsrc/index.rst’, for the standard file name.

4.4.15. DOCX_LIB¶

Sets the package path to the current package setupdocx. The package contains default components to be used by copy into the build directory of the created document.

See also Makefile_docx and make_docx.

4.4.16. DOCX_NAME¶

Sets the name of the package. Is set by the option –name. The default value is ‘self.name(package-name)’, for the current package name as set in the setup.py by the derived classes from setup.py.

See also DOCX_DOCNAME.

4.4.17. DOCX_NOEXEC¶

Sets the no-exec flag. Is set by the option –no-exec. The default value is False at environment the empty string - ‘’.

See also DOCX_DOCNAME.

4.4.18. DOCX_QUIET¶

Disables the verbose output, is treated by teh setuptools framework as negative option. for the special behavior refer to the option –verbose.
setup.py -build_docx -q
setup.py -build_docx -quiet
setup.py -q -build_docx
setup.py --quiet -build_docx
See also DOCX_QUIET.

4.4.19. DOCX_RAWDOC¶

Disables the production step call_apidoc.sh, thus no custom files are added to the current build. In combination with –apidoc the pure output from sphinx-apidoc is used as the resulting document. Is set by the option –rawdoc. The default value is ‘’, for non-disabled.

4.4.20. DOCX_RELEASE¶

Sets the release information. Is set by the option –set-release. The default value is ‘<YYYY-MM-DD>’, for the current date.

4.4.21. DOCX_SRCDIR¶

The name of the directories containing the source code of the project. Either a single name, or a string containing semicolon separated list of paths, similar to DOS-search paths. This syntax permits seamless inclusions of URIs.

DOCX_SRCDIR := <dir-name>[';'<srcdir>]

# default := <package-name>

4.4.22. DOCX_DOCTEMPLATE¶

The name of the configuration template to be used. Is set by the option –doctemplate. The default value is default - which is a currently a copy of alabaster - the hard-coded default of the Sphinx release at the time of writing. For the contained standard templates see –list-templates-std.

DOCX_DOCTEMPLATE := <template-name>

# default := 'default'

4.4.23. DOCX_VERBOSE¶

Raises the displayed state. This value is supported by distutils as global option, thus could be applied multiple times. The default value is ‘0’, for the minimal output.
setup.py --verbose --verbose --verbose build_docx
setup.py  -v -v -v -v build_docx
The following draft convention for the cumulative output of threshold levels is implemented:

No extra output

Basic display of control flow.

Display of resulting interface data.

Display of maximum output.

For the verbose flag of called external tools see –verbose-ext and DOCX_VERBOSEX.

4.4.24. DOCX_VERBOSEX¶

Activates the verbose flag(s) for called external tools when supported. These are currently sphinx-build and epydoc, which support the repetition of teh verbose flag -v. Raises the displayed state by the number of the provided integer value. Is set by the option –verbose-ext. The default value is ‘0’, for the minimal output.

4.4.25. DOCX_VERSION¶

Sets the version. Is set by the option –set-version. The default value is defined in setup.py, by the variable __version__.

4.5. DESCRIPTION¶

The call interface ‘setupdocx’ provides command line extensions for the command line call interface of setup.py. The curent version supports extension commands, future versions will support extension-points.

The build process is based on tools for the processing of sources and the resulting reST formats. The current toolset comprises sphinx-build, sphinx-apidoc, and epydoc. The intermediate documents are created within the directory:

<build-dir>/apidoc/sphinx

When finished the document is transferred into the directory:

<build-dir>/doc/<docname>

Thus within the same build directory only one document can be created at one time. When parallel build is required use different build directories –build-dir.

4.6. EXAMPLES¶

Import in your setup.py for example:

#
# setup extension modules
#
from setupdocx import usage
from setuptestx.testx import TestX  # for unit tests

from setupdocx.build_docx import BuildDocX      # create documents
from setupdocx.dist_docx import DistDocX        # package documents
from setupdocx.install_docx import InstallDocX  # install documents manually, or from sources


class build_docx(BuildDocX):
    def __init__(self, *args, **kargs):
        BuildDocX.__init__(self, *args, **kargs)
        self.name = 'setupdocx'                      # your package name


class dist_docx(BuildDocX):
    def __init__(self, *args, **kargs):
        BuildDocX.__init__(self, *args, **kargs)
        self.name = 'setupdocx'                      # your package name

class install_docx(InstallDocX):
    def __init__(self, *args, **kargs):
        InstallDocX.__init__(self, *args, **kargs)
        self.name = 'setupdocx'                      # your package name


class testx(TestX):
    def __init__(self, *args, **kargs):
        TestX.__init__(self, *args, **kargs)
        self.name = 'setupdocx'                      # your package name

Hook them in e.g. as a command in your setup.py by:

setup(
    cmdclass={                           # see [setuppy] and setup.py
        'build_docx': build_docx,
        'dist_docx': dist_docx,
        'install_docx': install_docx,
        'testx': testx,
    },
    ...
)

Use them from the command line call for example by:

python setup.py –help-setupdocx

python setup.py --help-commands           # see [setuppy]  and setup.py

python setup.py build_docx --help

python setup.py build_docx

python setup.py install_docx

4.7. SEE ALSO¶

Quick Start, setup.py, setup.conf, setupdocx, [setuptools], [distutils]

4.8. LICENSE¶

modified Artistic License = ArtisticLicense20 + Peer-to-Peer-Fairplay-amendments

For configuration files only:
MIT License

4.9. COPYRIGHT¶

Copyright (C)2019 Arno-Can Uestuensoez @Ingenieurbuero Arno-Can Uestuensoez