docs.eclass

Name

docs.eclass -- A simple eclass to build documentation.

Description

A simple eclass providing basic functions and variables to build documentation.

Please note that this eclass appends to RDEPEND and DEPEND unconditionally for you.

This eclass also appends doc to IUSE, and sets HTML_DOCS to the location of the compiled documentation automatically, einstalldocs will then automatically install the documentation to the correct directory.

The aim of this eclass is to make it easy to add additional doc builders. To do this, add a <DOCS_BUILDER>_deps and <DOCS_BUILDER>_compile function for your doc builder. For python based doc builders you can use the python_append_deps function to append [${PYTHON_USEDEP}] automatically to additional dependencies.

Example use doxygen:

DOCS_BUILDER="doxygen"
DOCS_DEPEND="media-gfx/imagemagick"
DOCS_DIR="docs"

inherit docs

...

src_compile() {
      default
      docs_compile
}

Example use mkdocs with distutils-r1:

DOCS_BUILDER="mkdocs"
DOCS_DEPEND="dev-python/mkdocs-material"
DOCS_DIR="doc"

PYTHON_COMPAT=( python3_{8..10} )

inherit distutils-r1 docs

...

Supported EAPIs

6 7 8

Functions

docs_compile

Calls DOCS_BUILDER and sets HTML_DOCS

This function must be called in src_compile. Take care not to overwrite the variables set by it. If distutils-r1 is inherited before this eclass, than docs_compile will be automatically added to python_compile_all() and there is no need to call it manually. Note that this function checks if USE="doc" is enabled, and if not automatically exits. Therefore, there is no need to wrap this function in a if statement.

Example use:

src_compile() {
    default
    docs_compile
}

Variables

DOCS_BUILDER (REQUIRED) (SET BEFORE INHERIT)

Sets the doc builder to use, currently supports sphinx, mkdocs and doxygen. PYTHON_COMPAT should be set for python based doc builders: sphinx and mkdocs

DOCS_DIR

Path containing the doc builder config file(s).

For sphinx this is the location of conf.py

For mkdocs this is the location of mkdocs.yml Note that mkdocs.yml often does not reside in the same directory as the actual doc files

For doxygen the default name is Doxyfile, but package may use a non-standard name. If this is the case one should set DOCS_CONFIG_NAME to the correct name

Defaults to ${S}

DOCS_DEPEND (SET BEFORE INHERIT)

Sets additional dependencies required to build the documentation. For sphinx and mkdocs these dependencies should be specified without [${PYTHON_USEDEP}], this is added by the eclass. E.g. to depend on mkdocs-material:

DOCS_DEPEND="dev-python/mkdocs-material"

This eclass appends to this variable, this makes it possible to call it later in your ebuild again if necessary.

DOCS_AUTODOC (SET BEFORE INHERIT)

Sets whether to use sphinx.ext.autodoc/mkautodoc Defaults to 1 (True) for sphinx, and 0 (False) for mkdocs. Not relevant for doxygen.

DOCS_OUTDIR

Sets the directory where the documentation should be built into. There is no real reason to change this. However, this variable is useful if the package should also install other HTML files.

Example use:

HTML_DOCS=( "${yourdocs}" "${DOCS_OUTDIR}/." )

Defaults to ${S}/_build/html

DOCS_CONFIG_NAME

Name of the doc builder config file.

Only relevant for doxygen, as it allows config files with non-standard names. Does not do anything for mkdocs or sphinx.

Defaults to Doxyfile for doxygen

Authors

Author: Andrew Ammerlaan <andrewammerlaan@gentoo.org>

Based on the work of: Michał Górny <mgorny@gentoo.org>

Maintainers

Andrew Ammerlaan <andrewammerlaan@gentoo.org>

Reporting Bugs

Please report bugs via https://bugs.gentoo.org/