pkgcore

pkgcore copied to clipboard

The final target is a good generator used for app-doc/eclass-manpages and for devmanual. There is a need for adding missing sections, and cleaning a lot of things! ulm requested the output as DocBook output. There are existing RST to DocBook convertors.

Resources:

• eclass → manpage
• manpage → html for devmanual
• rst → dockbook using docutils
• RST docutils spec

Bugs:

• https://bugs.gentoo.org/846503
• https://bugs.gentoo.org/773271
• https://github.com/pkgcore/pkgcore/issues/297

Project name:

pkgcore's devmanual eclass doc pages generator (pdedpg for short)

The final target is a good generator used for app-doc/eclass-manpages and for devmanual. There is a need for adding missing sections, and cleaning a lot of things! ulm requested the output as DocBook output. There are existing RST to DocBook convertors.

Not DocBook, but DevBook XML. See human readable and formal specs. It's a pretty simple format, especially when limited to eclass documentation, where there are no complicated elements like tables or figures.

If this should prove to be too difficult, then HTML would also be acceptable (after all, that's what we have now).

First of all, thank you @ulm for pointing me into the correct format (no idea how I managed to mistake docbook and devbook). I'm now in the process of writing a translator from rst to devbook (your links to explanation and spec were spot on). It progresses not bad, and the remaining shouldn't be too hard.

I think if this finishes as intended, we will have a good eclassdoc → {rst,manpage,devbook} convertor. Then I think we can decide that eclassdoc is rst format (not so far from current state, and then devs can better format them). Finally, I guess I can do a traversal of the eclasses to improve the format of eclassdoc, to better confirm. Main issues I find:

• missing blank line between bullet list items.
• too big indent for second line of explanations in bullet lists, which make it mistake with a definition list.

Current progress can be viewed here. This is a fully generated eclass docs as part of devmanual's Makefile, which only external need is the location of ::gentoo repo. There are still currently issues, and many future docs fixes needed, but we are close!