DOCS.ECLASS

Section: eclass-manpages (5)
Updated: Apr 2024
Index Return to Main Contents

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

7 8

FUNCTIONS

initialize_git_repo

Initializes a dummy git repository. This function is called by the documentation compile functions if DOCS_INITIALIZE_GIT is set. It can also be called manually.

sphinx_compile

Calls sphinx to build docs.

mkdocs_compile

Calls mkdocs to build docs.

doxygen_compile

Calls doxygen to build docs.

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
}

ECLASS 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

DOCS_INITIALIZE_GIT (SET BEFORE INHERIT)

Sometimes building the documentation will fail if this is not done inside a git repository. If this variable is set the compile functions will initialize a dummy git repository before compiling. A dependency on dev-vcs/git is automatically added.

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/

FILES

docs.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:01 GMT, April 25, 2024