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

2020-04-28 Thread Andrew Ammerlaan

On 28/04/2020 07:41, Joonas Niilola wrote:

On 4/27/20 7:10 PM, Andrew Ammerlaan wrote:

Hi all,


Hey,

could you please plaintext your whole patch in this thread, so it can be
viewed and commented by replying? See how lanodan did. Or check:

https://archives.gentoo.org/gentoo-dev/message/f2a7abcc8506ae3e56a0ebb0ea0cadc8

-- juippis


I inserted this below.


On 27/04/2020 22:37, Haelwenn (lanodan) Monnier wrote:

[2020-04-27 18:10:43+0200] Andrew Ammerlaan:

# Copyright 1999-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

# @ECLASS: docs.eclass
# @MAINTAINER:
# Andrew Ammerlaan 
# @AUTHOR:
# Author: Andrew Ammerlaan 
# Based on the work of: Michał Górny 
# @SUPPORTED_EAPIS: 5 6 7
# @BLURB: 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 -setup and
# -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
#
# For more information, please see the Python Guide:
# https://dev.gentoo.org/~mgorny/python-guide/

Should change this part to not be about python docs, right?



Thanks, this was a remnant from before I added doxygen support. I 
removed the line as it is not really relevant anymore.



case "${EAPI:-0}" in
0|1|2|3|4)
die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
;;
5|6|7)
;;
*)
die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
;;
esac

# @ECLASS-VARIABLE: DOCBUILDER
# @REQUIRED
# @PRE_INHERIT
# @DESCRIPTION:
# Sets the doc builder to use, currently supports
# sphinx and mkdocs

# @ECLASS-VARIABLE: DOCDIR
# @DESCRIPTION:
# Sets the location of the doc builder config file.

Suggestion:
Path containing the doc builder config file(s).


Thanks, changed it to this


commit 60ca34730b8a5b090997e2f48a522f615fe9b680
Author: Andrew Ammerlaan 
Date:   Sat Apr 11 10:57:44 2020 +0200

    eclass/docs: setup mkdocs deps and build docs

    works with sphinx and mkdocs. Based on distutils_enable_sphinx,
    but unlike distutils also works for non-python packages

    Package-Manager: Portage-2.3.98, Repoman-2.3.22
    Signed-off-by: Andrew Ammerlaan 

diff --git a/eclass/docs.eclass b/eclass/docs.eclass
new file mode 100644
index 000..f3d4eb2ce41
--- /dev/null
+++ b/eclass/docs.eclass
@@ -0,0 +1,365 @@
+# Copyright 1999-2020 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+# @ECLASS: docs.eclass
+# @MAINTAINER:
+# Andrew Ammerlaan 
+# @AUTHOR:
+# Author: Andrew Ammerlaan 
+# Based on the work of: Micha艂 G贸rny 
+# @SUPPORTED_EAPIS: 5 6 7
+# @BLURB: 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 -setup and
+# -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.
+
+case "${EAPI:-0}" in
+    0|1|2|3|4)
+        die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
+        ;;
+    5|6|7)
+        ;;
+    *)
+        die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
+        ;;
+esac
+
+# @ECLASS-VARIABLE: DOCBUILDER
+# @REQUIRED
+# @PRE_INHERIT
+# @DESCRIPTION:
+# Sets the doc builder to use, currently supports
+# sphinx, mkdocs and doxygen
+
+# @ECLASS-VARIABLE: DOCDIR
+# @DESCRIPTION:
+# 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}
+
+# @ECLASS-VARIABLE: DOCDEPEND
+# @DEFAULT_UNSET
+# @PRE_INHERIT
+# @DESCRIPTION:
+# 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:
+#
+# DOCDEPEND="dev-python/mkdocs-material"
+#
+# This eclass appends to this variable, so you can
+# call it later in your ebuild again if necessary.
+
+# @ECLASS-VARIABLE: AUTODOC
+# @PRE_INHERIT
+# @DESCRIPTION:
+# Sets whether to use sphinx.ext.autodoc/mkautodoc
+# Defaults to 1 (True) 

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

2020-04-27 Thread Joonas Niilola

On 4/27/20 7:10 PM, Andrew Ammerlaan wrote:
> Hi all,
>
Hey,

could you please plaintext your whole patch in this thread, so it can be
viewed and commented by replying? See how lanodan did. Or check:

https://archives.gentoo.org/gentoo-dev/message/f2a7abcc8506ae3e56a0ebb0ea0cadc8

-- juippis




signature.asc
Description: OpenPGP digital signature


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

2020-04-27 Thread Haelwenn (lanodan) Monnier
[2020-04-27 18:10:43+0200] Andrew Ammerlaan:
> # Copyright 1999-2020 Gentoo Authors
> # Distributed under the terms of the GNU General Public License v2
> 
> # @ECLASS: docs.eclass
> # @MAINTAINER:
> # Andrew Ammerlaan 
> # @AUTHOR:
> # Author: Andrew Ammerlaan 
> # Based on the work of: Michał Górny 
> # @SUPPORTED_EAPIS: 5 6 7
> # @BLURB: 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 -setup and
> # -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
> #
> # For more information, please see the Python Guide:
> # https://dev.gentoo.org/~mgorny/python-guide/

Should change this part to not be about python docs, right?

> 
> case "${EAPI:-0}" in
>   0|1|2|3|4)
>   die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
>   ;;
>   5|6|7)
>   ;;
>   *)
>   die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
>   ;;
> esac
> 
> # @ECLASS-VARIABLE: DOCBUILDER
> # @REQUIRED
> # @PRE_INHERIT
> # @DESCRIPTION:
> # Sets the doc builder to use, currently supports
> # sphinx and mkdocs
> 
> # @ECLASS-VARIABLE: DOCDIR
> # @DESCRIPTION:
> # Sets the location of the doc builder config file.

Suggestion:
Path containing the doc builder config file(s).



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

2020-04-27 Thread 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

# Copyright 1999-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

# @ECLASS: docs.eclass
# @MAINTAINER:
# Andrew Ammerlaan 
# @AUTHOR:
# Author: Andrew Ammerlaan 
# Based on the work of: Michał Górny 
# @SUPPORTED_EAPIS: 5 6 7
# @BLURB: 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 -setup and
# -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
#
# For more information, please see the Python Guide:
# https://dev.gentoo.org/~mgorny/python-guide/

case "${EAPI:-0}" in
0|1|2|3|4)
die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
;;
5|6|7)
;;
*)
die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
;;
esac

# @ECLASS-VARIABLE: DOCBUILDER
# @REQUIRED
# @PRE_INHERIT
# @DESCRIPTION:
# Sets the doc builder to use, currently supports
# sphinx and mkdocs

# @ECLASS-VARIABLE: DOCDIR
# @DESCRIPTION:
# Sets the location of the doc builder config file.
#
# 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}

# @ECLASS-VARIABLE: DOCDEPEND
# @DEFAULT_UNSET
# @PRE_INHERIT
# @DESCRIPTION:
# 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:
#
# DOCDEPEND="dev-python/mkdocs-material"
#
# This eclass appends to this variable, so you can
# call it later in your ebuild again if necessary.

# @ECLASS-VARIABLE: AUTODOC
# @PRE_INHERIT
# @DESCRIPTION:
# Sets