7.11. setupdocx.build_docx

The standard implementation:

python setup.py build_docx

Tested alternative implementations:

ipython setup.py build_docx
jython  setup.py build_docx  # requires special install of setuptools, refer to the manuals
pypy    setup.py build_docx
ipw.exe setup.py build_docx  # IronPython on Windows

Call for the online description of current options:

python setup.py build_docx --help

The detailed description is available in the manual.

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


Synopsis:
  setup.py [global-options] build_docx [build_docx-options]

Global options for 'setup.py':
  --dry-run (-n)  don't actually do anything
  --help (-h)     show detailed help message
  --no-user-cfg   ignore pydistutils.cfg in your home directory
  --quiet (-q)    run quietly (turns verbosity off)
  --verbose (-v)  run verbosely (default)

Options for 'build_docx' command:
  --apiref                Calls the script 'call_apiref.sh', creates the API
                          reference and integrates into sphinx, else sphinx
                          only. default: None
  --break-on-err          Sets the environment variable 'DOCX_BREAKONERR' for
                          the called wrapper script. Breaks after the first
                          error state from the called builder. Default: 'off'
  --builder               The builder to be used for the processing of the
                          document. See '--help-builder'. Default: 'sphinx'
  --builder-path          The directory path of the builder. Default:
                          '<SETUPDOCX-PYTHONPATH>/setupdocx/builder/'
  --build-dir             The name of the build directory. Default: 'build/'
  --build-reldir          The name of the relative build subdirectory.
                          Default: 'apidoc/<builder>/'
  --cap                   The initial default values, for an example see the
                          builder capabilities.One or more values separated by
                          comma ','.No search operation, the name bust be an
                          existing file path name.This is an expert and
                          developer option, which should not be used
                          regularly.Default:
                          'setupdocx/builder/<builder>/capabilities'
  --clean                 Removes the cached previous build. The default
                          directory is '<build-dir>/apidoc'.Default: False
  --clean-all             Removes the complete build directory before calling
                          the wrapper. The default directory is '<build-
                          dir>'.Default: False
  --config-path           Directory containing configuration files. See '--
                          list-templates-std' and '--list-templates'. Default:
                          '<docsource>/config/'.
  --copyright             A copyright text to be used literally. Default: (C)
                          <year> <author>.
  --debug (-d)            Raises degree of debug traces of current context.
                          Supports repetition. Each raises the command
                          verbosity level of the context by one.
  --docname               The document output name. Default: attribute of
                          derived class self.name
  --docsource             The name of the document source directory. Default:
                          docsrc/
  --doctemplate           The document template directory relative to '--
                          config-path'. See '--list-templates-std' and '--list
                          -templates'. Default: default/html
  --doctype               The document type to create. See '--help-doctypes'
                          for common types, for present types see '--list-
                          templates-std' and '--list-templates'. Default:
                          'html',
  --executable            The executable called by the wrapper. Supports
                          relative and absolute file path names. Default:
                          'sphinx-build'
  --executableopts        Additional options to be passed to the executable.
                          Default: ''
  --executableopts-reset  Initialize empty options for the called executable.
                          Default: False
  --help-doctypes         List of available document formats.
  --indexsrc              The source file to be copied as 'index.rst'.
                          Default: 'index.rst'
  --list-templates-std    List provided configuration templates.
  --list-templates        Lists the configuration templates with filter
                          parameter, see manuals. Default: same as list-
                          templates-std
  --name                  The name of the package. Default: attribute of
                          derived class self.name
  --noexec (-n)           Print the call of the selected level only, do not
                          execute. The value is an integer, decremented by
                          each level until '0',which is the level to be
                          printed.
  --quiet (-q)            Quiet the current context, resets verbosity of
                          applied context to '0'. Default: off
  --rawdoc (-r)           Use the generated documents by 'apidoc' only.
  --srcdir                Source directory.
  --set-release           The release of the package.Default:
                          distribution.metadata.version
  --set-version           The version of the package. Default:
                          distribution.metadata.version
  --status                The status in accordance to the trove classifiers.
                          Default: '' - empty
  --wrapper               The wrapper called by the builder. Supports pure
                          file names only. Default: 'call_doc.sh'
  --wrapperopts           Additional options to be passed to the called
                          wrapper. Default: ''
  --wrapperopts-reset     Drop generated options for the wrapper, does not
                          effect environment. Default: False
  --verbose (-v)          Raises verbosity of current context. Supports
                          repetition. Each raises the command verbosity level
                          of the context by one.
  --apidoc                Calls the script 'call_apidoc.sh', creates the API
                          documentation and integrates into sphinx, else
                          sphinx-build only. default: None
  --builder               Builder to be used for the document processing.
                          Default: 'sphinx' dependent of the doctype resulting
                          in pure 'sphinx-build' for inherent document types,
                          or 'sphinx-build' + 'make' for external types
                          defined by '--doctype' e.g. such as 'html' or
                          'epub'. For called code-analysis tools see '--
                          builder-apidoc' and '--builder-apiref'.See '--help-
                          builder' for a list of available builders.
  --build-apidoc          the name of the called script for the creation of
                          the API documentation, default: '<conf-
                          dir>/call_apidoc.sh'
  --build-apiref          the name of the called script for the creation of
                          the API reference, default: '<conf-
                          dir>/call_apiref.sh'
  --build-doc             the name of the called script for the sphinx
                          document creation, default: '<conf-dir>/call_doc.sh'

(3.8.0) [acue@lap001 setupdocx]$

7.11.3. Module

Creates extended documentation based on configuration templates. Supports optional extraction of inline documentation and creation of additional structured Javadoc style API reference from inline documentation.

Supports abstract configuration templates for various document builders e.g. Sphinx, MkDocs, Epydoc, TexInfo, Docbook, Perldoc, and txt2tags. Could be easily extended by custom wrappers.

Is foreseen as the common abstract build API for the template based creation of local and online documentation.

7.11.4. BuildDocX

class setupdocx.build_docx.BuildDocX(dist)[source]

Create compound documents.

7.11.4.1. call_environment

BuildDocX.call_environment()[source]

Sets the specific environment variables for the subprocess. In addition writes source files of the environment for the manual command line start.

The defined variables represent the interface to the wrapper calls, so no modification of the provided environment is permitted. When additional information is required do not forget to call this method.

7.11.4.2. call_epilogue

BuildDocX.call_epilogue()[source]

Executed after the call of the wrapper.

7.11.4.3. call_prologue

BuildDocX.call_prologue()[source]

Executed before the call of the wrapper.

The default version supports Sphinx and writes the project data into the file ‘<build-dir>/<build-reldir>/project.rst’. Replace this method in the derived class as required.

7.11.4.4. finalize_options

BuildDocX.finalize_options()[source]

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

7.11.4.5. initialize_options

BuildDocX.initialize_options()[source]

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

7.11.4.6. run

BuildDocX.run()[source]

Creates documents. Calls the defined and activated wrapper scripts. The call flow could be customized by various interfaces.

I.      self.call_environment()    # could be superposed by derived class
II.     self.call_prologue()       # could be superposed by derived class
III.    subprocesses:
    1.    build_apidoc.sh          # could be arbitrary custom call wrapper
    2.    build_docx.sh            # could be arbitrary custom call wrapper
    3.    build_apiref.sh          # could be arbitrary custom call wrapper
IV.     self.call_epilogue()       # could be superposed by derived class

For the called custom worker scripts refer to:

For the passed environment variables see ENVIRONMENT.

7.11.4.7. join_sphinx_mod_epydoc

Note

This is method is displayed for general documetation purposes only. Currently hardcoded, will be changed for flexible customization in future releases.

BuildDocX.join_sphinx_mod_epydoc(dirpath)[source]

Integrates links for sphinx into the the sidebar of the output of epydoc.

Adds the following entries before the “Table of Contents” to the sphinx document:

  • Home

  • Top

Note

This method is subject to be changed. Current version is hardcoded, see documents. Following releases will add customization.

Parameters

dirpath – Directory path to the file ‘index.html’.

Returns

None

Raises

None –

7.11.5. Exceptions

exception setupdocx.build_docx.SetuplibBuildDocXError[source]

Generic command error.

7.11.5.1. Source

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
PROJECT='setupdocx'
VERSION=${DOCX_VERSION:-`date +%Y.%m.%d`}
RELEASE=${DOCX_RELEASE:-$VERSION}
AUTHOR='Arno-Can Uestuensoez'
COPYRIGHT='Copyright (C) 2019 Arno-Can Uestuensoez @Ingenieurbuero Arno-Can Uestuensoez'
LICENSE='Artistic-License-2.0 + Forced-Fairplay-Constraints'
STATUS='beta'
MISSION='Support extensions for setuptools / distutils.'
BUILDDATE=`date`

cat <<EOF
################################################################
#                                                              #
$(printf "# PROJECT = %-51s#" $PROJECT)
#                                                              #
# Generate API reference - default: epydoc                     #
#                                                              #
################################################################
EOF

# the absolute pathname for this source
MYPATH="${BASH_SOURCE%/*}/"
if [ "X${MYPATH#.}" != "X$MYPATH" ];then
	MYPATH="${PWD}/${MYPATH#.}";MYPATH="${MYPATH//\/\//\/}"
fi

# input base directory
INDIR="${INDIR:-$PWD}"
if [ "X${INDIR#.}" != "X$INDIR" ];then
	INDIR="${PWD}/${INDIR#.}";INDIR="${INDIR//\/\//\/}"
fi
INDIR="${INDIR}/"

# output base directory
DOCX_BUILDDIR="${DOCX_BUILDDIR:-build}/"
if [ ! -e "${DOCX_BUILDDIR}" ];then
	mkdir -p "${DOCX_BUILDDIR}"
fi
export PYTHONPATH="$PWD:$PYTHONPATH"

# document source directory
DOCX_DOCSRC="${DOCX_DOCSRC:-docsrc}"
DOCX_DOCSRC="${DOCX_DOCSRC%%/}"


# document source directory
DOCX_DOCNAME="${DOCX_DOCNAME:-$PROJECT}"


DOCX_VERBOSE=${DOCX_VERBOSE:-0}
if((DOCX_VERBOSE > 1));then
	echo "${0##*/}:Called:"
	echo "  $0 $@"
	echo "${0##*/}:Environ Options:"
	echo "  DOCX_APIREF      = '$DOCX_APIREF'"
	echo "  DOCX_BUILDDIR    = '$DOCX_BUILDDIR'"
	echo "  DOCX_CONFDIR     = '$DOCX_CONFDIR'"
	echo "  DOCX_DOCNAME     = '$DOCX_DOCNAME'"
	echo "  DOCX_DOCSRC      = '$DOCX_DOCSRC'"
	echo "  DOCX_DOCTYPE     = '$DOCX_DOCTYPE'"
	echo "  DOCX_NAME        = '$DOCX_NAME'"
	echo "  DOCX_INDEXSRC    = '$DOCX_INDEXSRC'"
	echo "  DOCX_RAWDOC      = '$DOCX_RAWDOC'"
	echo "  DOCX_RELEASE     = '$DOCX_RELEASE'"
	echo "  DOCX_SRCDIR      = '$DOCX_SRCDIR'"
	echo "  DOCX_VERBOSE     = '$DOCX_VERBOSE'"
	echo "  DOCX_VERSION     = '$DOCX_VERSION'"

	echo "  PATH             = '$PATH'"
	echo "  PYTHONPATH       = '$PYTHONPATH'"
	echo "  MYPATH           = '$MYPATH'"
	echo "  INDIR            = '$INDIR'"
	echo
fi

#
# *** start exec ***
#

if [ -e "${DOCX_CONFDIR}/epydoc.conf" ];then
	REFCONF="${DOCX_CONFDIR}/epydoc.conf"
else
	REFCONF="${DOCX_DOCSRC}/conf/epydoc.conf"	
fi
if [ -e "${DOCX_CONFDIR}/epydoc.css" ];then
	REFCSS="${DOCX_CONFDIR}/epydoc.css"
else
	REFCSS="${DOCX_DOCSRC}/conf/epydoc.css"	
fi


CALL=""
CALL="$CALL export PYTHONPATH=$PWD:$PYTHONPATH;"
CALL="$CALL epydoc "
CALL="$CALL --html "
CALL="$CALL --name '${DOCX_NAME}'"
# CALL="$CALL --url 'https://my/url'"
CALL="$CALL --config '${REFCONF}'"
CALL="$CALL --css '${REFCSS}'"
CALL="$CALL --output '${DOCX_BUILDDIR}/apidoc/${DOCX_DOCNAME}/apiref' "

if((DOCX_VERBOSE > 1));then
	for((i=0;i<DOCX_VERBOSE;i++));do
		CALL="$CALL -v "
	done
fi

CALL="$CALL $@"

if [ ! -e "${DOCX_BUILDDIR}/sphinx/apidoc/apiref" ];then
	mkdir -p "${DOCX_BUILDDIR}/sphinx/apidoc/apiref"
fi

if((DOCX_VERBOSE > 1));then
	echo
	echo "${0##*/}:Call: $CALL"
	echo
fi


eval $CALL

echo

7.11.5.2. Download

call_apiref.sh