Gentoo Archives: gentoo-dev

From: Andrew Ammerlaan <andrewammerlaan@××××××.net>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] Fwd: New eclass suggestion: docs.eclass
Date: Mon, 27 Apr 2020 16:10:52
1 Hi all,
4 I've been working with some mkdocs-* related ebuilds, and I kept having
5 to do the same lines over and over again to get things to build the
6 documentation. Therefore, I felt that it might be useful to automate
7 this a bit with an eclass. However, because mkdocs is a relatively
8 small, I tried to write a somewhat more generic eclass that supports
9 multiple doc builders. So far I have added support for mkdocs, sphinx
10 and doxygen.
12 The functions are based on the `distutils_enable_sphinx` function from
13 the distutils-r1 eclass (but unlike the distutils function, sphinx
14 building also works for non-python packages in the docs eclass). The
15 generic parts have been stripped out and put into the generic part of
16 the eclass. Each doc builder has it's own _setup function to set up the
17 dependencies, and _compile function which calls the documentation
18 builder and deals with things specific to that doc builder. The rest
19 should be pretty self explanatory (I hope).
21 In my opinion it is very easy to use, e.g.:
23 ```
25 DOCBUILDER="mkdocs" (or "sphinx" or "doxygen" )
27 DOCDEPEND="dev-python/mkdocs-material" (additional doc deps, apart from
28 the doc builder itself)
30 inherit docs
32 ```
35 There are some more variables which can be set for more advanced use
36 cases (e.g. DOCDIR if the docs are not in ${S}), see the in-file
37 documentation. And see
39 for an example.
42 I'd be very interested to hear what you all think of this eclass, and if
43 it would make a nice addition to ::gentoo? I'd also be interested to
44 hear about any other documentation builders that might be added to the
45 eclass (I tried to write it such that it is easy to add support for more
46 doc builders). (Juippis already suggested to add doxygen yesterday in
47 )
49 There are some mkdocs related ebuilds in the guru overlay
50 that this eclass can be tested on (e.g.
51 mkdocs-material). Though a circular dependency prevents from setting
52 USE="doc" on the entire overlay (mkdocs-material depends on things,
53 whose documentation depends on mkdocs-material again), it is easily
54 resolved by first emerging those packages with USE="-doc".
56 I already tested this in every use case I could think of, mkdocs/sphinx
57 python ebuild, mkdocs non-python ebuild, doxygen ebuild, sphinx with and
58 without autodoc, mkdocs with and without mkautodoc, docs in a subdir.
59 And so far it seems to be working just fine. It's also been in the guru
60 overlay for quite some time already.
62 Please let me know if you find any issues, or potential improvements.
64 Best Regards,
66 Andrew
68 See Also:


File name MIME type
docs.eclass text/plain


Subject Author
Re: [gentoo-dev] Fwd: New eclass suggestion: docs.eclass "Haelwenn (lanodan) Monnier" <contact@×××××××××.me>
Re: [gentoo-dev] Fwd: New eclass suggestion: docs.eclass Joonas Niilola <juippis@g.o>