DOCS.ECLASS

Section: eclass-manpages (5)
Updated: Oct 2021
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

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
}

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

AUTHORS

Author: Andrew Ammerlaan <andrewammerlaan@gentoo.org>
Based on the work of: Micha[u0142] G[u00F3]rny <mgorny@gentoo.org>

MAINTAINERS

Andrew Ammerlaan <andrewammerlaan@gentoo.org>

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, October 16, 2021