DOCS.ECLASS
Section: eclass-manpages (5)Updated: Nov 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 8FUNCTIONS
- 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: Nowa Ammerlaan <[email protected]>Based on the work of: Michał Górny <[email protected]>
MAINTAINERS
Nowa Ammerlaan <[email protected]>REPORTING BUGS
Please report bugs via https://bugs.gentoo.org/FILES
docs.eclassSEE 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:01 GMT, November 25, 2024