DOCS.ECLASS

Section: eclass-manpages (5)
Updated: Jan 2021
Index Return to Main Contents

NAME

docs.eclass - A simple eclass to build documentation.

DESCRIPTION

A simple eclass providing functions to build documentation.

Please note that docs sets RDEPEND and DEPEND unconditionally for you.

This eclass also appends "doc" to IUSE, and sets HTML_DOCS to the location of the compiled documentation

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

SUPPORTED EAPIS

6 7

FUNCTIONS

python_append_dep
Appends [{PYTHON_USEDEP}] to all dependencies for python based DOCS_BUILDERs such as mkdocs or sphinx.
sphinx_deps
Sets dependencies for sphinx
sphinx_compile
Calls sphinx to build docs.

If you overwrite src_compile or python_compile_all do not call this function, call docs_compile instead

mkdocs_deps
Sets dependencies for mkdocs
mkdocs_compile
Calls mkdocs to build docs.

If you overwrite src_compile or python_compile_all do not call this function, call docs_compile instead

doxygen_deps
Sets dependencies for doxygen
doxygen_compile
Calls doxygen to build docs.

If you overwrite src_compile or python_compile_all do not call this function, call docs_compile instead

docs_compile
Calls DOCS_BUILDER and sets HTML_DOCS

This function must be called in global scope. Take care not to overwrite the variables set by it. Has support for distutils-r1 eclass, but only if this eclass is inherited *after* distutils-r1. If you need to extend src_compile() or python_compile_all(), you can call the original implementation as 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

Defaults to ${S}

DOCS_DEPEND (SET BEFORE INHERIT)
Sets additional dependencies to build docs. 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, so you can 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
DOCS_OUTDIR
Sets where the compiled files will be put. There's no real reason to change this, but this variable is useful if you want to overwrite the HTML_DOCS added by this eclass. E.g.:

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

Defaults to Doxyfile for doxygen

AUTHORS

Author: Andrew Ammerlaan <andrewammerlaan@riseup.net>
Based on the work of: Michał Górny <mgorny@gentoo.org>

MAINTAINERS

Andrew Ammerlaan <andrewammerlaan@riseup.net>

REPORTING BUGS

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

FILES

docs.eclass

SEE ALSO

ebuild(5)
https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/docs.eclass


Index

NAME
DESCRIPTION
SUPPORTED EAPIS
FUNCTIONS
ECLASS VARIABLES
AUTHORS
MAINTAINERS
REPORTING BUGS
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 03:27:02 GMT, January 17, 2021