[ClusterLabs Developers] [RFC][pacemaker] Antora as a successor for the current publication platform base on (abandoned?) publican

Ken Gaillot kgaillot at redhat.com
Thu Jan 17 21:30:37 UTC 2019


On Thu, 2019-01-17 at 21:00 +0100, Jan Pokorný wrote:
> I am now talking about documents as available, e.g., at:
> 
> https://clusterlabs.org/pacemaker/doc/ (Versioned documentation)
> 
> Sadly, I've come to realize that publican is no longer being
> developed, and while this alone is bearable since it fulfills

Bummer. We'll have to move on sooner or later ...

> its role well, worse, some distros are not (going to be) packaging
> it anymore.  Also, think of staying up-to-date with target formats
> and "pleasing aesthetics of the decade".
> 
> For instance, also Fedora project, ironically with the intimately
> strongest inclination towards this project, decided to ditch it in
> favour of Antora:
> 
> https://fedoramagazine.org/fedora-docs-overhaul/
> 
> On the first sight, getting rid of publican looked well -- the less
> extensive dependencies (like Perl ecosystem) the better.  But the
> crux is that Antora is possibly even worse in this regard :-D
> Good thing about Antora, though, is that it natively works with
> with AsciiDoc formatted files, just as we already do, e.g.:
> 
> 
https://github.com/ClusterLabs/pacemaker/tree/Pacemaker-2.0.1-rc2/doc/Pacemaker_Explained/en-US

Antora looks interesting. The biggest downside vs publican is that it
appears to be only a static website generator, i.e. it would not
generate PDF, epub, or single-page HTML the way we do now.

> My ask is then: how you feel about this possible change (addressing
> intentionallh YOU on this very list, as an existing or possible
> future
> contributor), if you know of some other tool comparable to publican,
> or if you think we might be served with some other approach to
> mastering publications with as little friction as possible (staying
> with AsciiDoc preferred for the time being) unless we get something
> really appealing in return (is there any cherry like that with, e.g.,
> Sphinx?).

Sphinx looks like it covers everything we offer now, and it's likely to
be actively maintained for a long while, given that it's used for the
Python docs as well as hundreds of smaller projects.

I don't see much else out there. There are some hosted options, like
readthedocs.org and gitbook.com, that pull raw source from a github
repo and generate a hosted website from it. gitbook also has an easy
editing interface for people who don't want to edit source.

> I figure also downstream has possibly something to say here
> if they are after shipping such handbooks as well.
> 
> Thanks for your inputs.

Another outstanding question is what to do about translations. I've
disabled them since they got really out of date and aren't actively
maintained. Our docs are updated more frequently than they used to be,
so any translators would have a nontrivial ongoing commitment. We could
use something like zanata.org to make contributing easier. Or, we could
give up and drop translations, until/unless the community grows
significantly larger.
-- 
Ken Gaillot <kgaillot at redhat.com>




More information about the Developers mailing list