[gentoo-dev] Fwd: New eclass suggestion: docs.eclass

[Andrew Ammerlaan]

Hi all,


I've been working with some mkdocs-* related ebuilds, and I kept having 
to do the same lines over and over again to get things to build the 
documentation. Therefore, I felt that it might be useful to automate 
this a bit with an eclass. However, because mkdocs is a relatively 
small, I tried to write a somewhat more generic eclass that supports 
multiple doc builders. So far I have added support for mkdocs, sphinx 
and doxygen.

The functions are based on the `distutils_enable_sphinx` function from 
the distutils-r1 eclass (but unlike the distutils function, sphinx 
building also works for non-python packages in the docs eclass). The 
generic parts have been stripped out and put into the generic part of 
the eclass. Each doc builder has it's own _setup function to set up the 
dependencies, and _compile function which calls the documentation 
builder and deals with things specific to that doc builder. The rest 
should be pretty self explanatory (I hope).

In my opinion it is very easy to use, e.g.:

```

DOCBUILDER="mkdocs" (or "sphinx" or "doxygen" )

DOCDEPEND="dev-python/mkdocs-material" (additional doc deps, apart from 
the doc builder itself)

inherit docs

```


There are some more variables which can be set for more advanced use 
cases (e.g. DOCDIR if the docs are not in ${S}), see the in-file 
documentation. And see 
https://gitweb.gentoo.org/repo/proj/guru.git/tree/dev-python/mkdocs-material/mkdocs-material-5.1.1.ebuild?h=dev 
for an example.


I'd be very interested to hear what you all think of this eclass, and if 
it would make a nice addition to ::gentoo? I'd also be interested to 
hear about any other documentation builders that might be added to the 
eclass (I tried to write it such that it is easy to add support for more 
doc builders). (Juippis already suggested to add doxygen yesterday in 
https://github.com/gentoo/gentoo/pull/15302 )

There are some mkdocs related ebuilds in the guru overlay 
https://github.com/gentoo/guru that this eclass can be tested on (e.g. 
mkdocs-material). Though a circular dependency prevents from setting 
USE="doc" on the entire overlay (mkdocs-material depends on things, 
whose documentation depends on mkdocs-material again), it is easily 
resolved by first emerging those packages with USE="-doc".

I already tested this in every use case I could think of, mkdocs/sphinx 
python ebuild, mkdocs non-python ebuild, doxygen ebuild, sphinx with and 
without autodoc, mkdocs with and without mkautodoc, docs in a subdir. 
And so far it seems to be working just fine. It's also been in the guru 
overlay for quite some time already.

Please let me know if you find any issues, or potential improvements.

Best Regards,

Andrew

See Also: https://github.com/gentoo/gentoo/pull/15302