[gentoo-dev] Using RST for eclassdoc

[Arthur Zamarin <arthurzam@gentoo.org>]

[-- Attachment #1.1.1: Type: text/plain, Size: 2501 bytes --]

Hi all

For a very long time, we had a WIP branch for pkgcore [1], where I tried
to implement parsing of eclassdoc, and convert them to devbook (the
format used by devmanual), which the devmanual [2] then would convert to
html using the normal converter used there. So, why was this wanted and
what happened since?

------------ History ------------

Our eclassdocs consist of special tags (such as "@INTERNAL" and
"@DESCRIPTION") which represent various information. The free-text part
is without real rules on formattinf, meaning we can't really say "this
is code", "bold this text", "this is a numeric list", "this is bullet
list". We have used various hacks and stuff, and it worked mostly. There
was a complicated tool which converted those eclassdoc into man page,
and then the man page was converted to html.

On 2022-05, I was requested to investigate the possibility of using
pkgcore for preparing those files, with selection of RST as the
formatting syntax. I've managed to do it and it worked, with also a
possibility for pkgcore generating the man pages.

But as expected, we had various eclasses whose eclassdoc wasn't exactly
matching, and also various eclass' format could be improved. I've worked
on it at the PR [3], but for the huge take of verifying all eclasses, I
tired it out. Yes, this was a mistake on my part.

To see the state where we can get and why, look at my devspace [4] to
see the result for the very old PR [3].

--------- Current state ---------

I've merged into pkgcore the devbook code generator. You need
pkgcore-9999 for that.
You need my changes to the build of devmanual at [2].

We need to declare that from now on eclassdoc uses RST format, so at
least future changes would not break us. I'll again say that RST isn't
too far from what we used today, so this isn't a big change. Maybe this
should be put in a GLEP?

We need to fix the eclassdoc of the "broken eclasses". I've attached a
file listed all of them. Just run `make` on the devmanual and you can
see in the relevant eclass html file a warning box with the issue. Most
of the time it is adding `` for marking it as code.


[1] https://github.com/pkgcore/pkgcore/pull/346
[2] https://github.com/gentoo/devmanual/pull/317
[3] https://github.com/gentoo/gentoo/pull/27646
[4] https://dev.gentoo.org/~arthurzam/devmanual/eclass-reference/index.html
-- 
Arthur Zamarin
arthurzam@gentoo.org
Gentoo Linux developer (Python, pkgcore stack, Arch Teams)

[-- Attachment #1.1.2: broken-eclassdoc.txt --]
[-- Type: text/plain, Size: 1001 bytes --]

alternatives.eclass
apache-2.eclass
apache-module.eclass
autotools.eclass
bazel.eclass
check-reqs.eclass
cmake.eclass
common-lisp-3.eclass
cvs.eclass
distutils-r1.eclass
dotnet-pkg.eclass
elisp.eclass
flag-o-matic.eclass
ghc-package.eclass
git-r3.eclass
gnome2-utils.eclass
golang-vcs-snapshot.eclass
go-module.eclass
haskell-cabal.eclass
java-ant-2.eclass
java-osgi.eclass
java-pkg-simple.eclass
java-utils-2.eclass
kernel-build.eclass
latex-package.eclass
linux-info.eclass
linux-mod-r1.eclass
lua.eclass
lua-single.eclass
mate.eclass
mercurial.eclass
mozlinguas-v2.eclass
multilib-build.eclass
pax-utils.eclass
perl-functions.eclass
perl-module.eclass
postgres-multi.eclass
prefix.eclass
python-any-r1.eclass
python-r1.eclass
python-single-r1.eclass
qt6-build.eclass
ruby-ng.eclass
ruby-single.eclass
rust-toolchain.eclass
secureboot.eclass
stardict.eclass
subversion.eclass
systemd.eclass
toolchain-funcs.eclass
verify-sig.eclass
versionator.eclass
vim-spell.eclass
webapp.eclass
xdg-utils.eclass

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]