From Fedora Project Wiki

Line 22: Line 22:
* perl(Config::Simple) -- sixy
* perl(Config::Simple) -- sixy
* perl(DateTime::Format::DateParse) -- cweyl
* perl(DateTime::Format::DateParse) -- cweyl
* perl(File::pushd) -- mmaslano * (built -- need to push stable)
* perl(File::pushd) -- mmaslano * (built for EPEL -- need to push stable)
* perl(Locale::PO) -- iarnell -- package change requested
* perl(Locale::PO) -- iarnell -- package change requested for EPEL
* perl(Makefile::Parser) -- nb
* perl(Makefile::Parser) -- nb
* perl(Syntax::Highlight::Engine::Kate) -- mmaslano
* perl(Syntax::Highlight::Engine::Kate) -- mmaslano
* fop -- langel/lkundrak * (added -- need to build)
* fop -- langel/lkundrak * (branched for EPEL -- need to build)
* batik -- langel
* batik -- langel

Revision as of 09:06, 18 July 2010

This page tracks progress towards implementing a fully automated publishing process for the Fedora Documentation Project.


Formal Fedora documentation is authored in DocBook XML and transformed into multi-page HTML, single-page HTML, PDF, and EPUB by our publishing tool, Publican. Publican also generates the tables of contents in each language that provide navigation.

At present, the entire documentation suite hosted at resides in a Git repository to which certain members of the Documentation Project (members of the docs-publishers group) commit changes. The webserver publishes whatever is in that repo.

This is a vast improvement over our previous process, but Publican includes features that make publishing even easier and more robust, since Publican is designed to package documentation in RPM packages to install on a webserver. Chapter 6 of the Publican Users' Guide provides an overview of the mechanism.

Important -- note that since the webserver runs Red Hat Enterprise Linux 5, the documentation packages need to be built for Red Hat Enterprise Linux 5. Publican is also designed to build documentation to install for desktop use, but this is a separate set of considerations and not the aim here.

Steps to automate publishing

Install Publican 2 on the webserver

Publican 2 is the first version that includes the web publishing components. However, Publican 2 has a number of dependencies that are either not in Red Hat Enterprise Linux 5 at all, or which are in Red Hat Enterprise Linux 5 in versions too old for Publican 2. While we could build dependencies in the former group in EPEL, we cannot build dependencies in the latter group in EPEL since EPEL packages must not update packages in Red Hat Enterprise Linux, only provide packages that are not shipped at all.

To install Publican 2 on the webserver, we need to

  • either provide the dependencies not in el5 in the dist-5E-epel-infra repo, or (better) get them built for EPEL
  • either provide the dependencies in el5 in older versions in the dist-5E-epel-infra repo, or (better) build them in Koji for dist-5E-epel-infra.
  • either provide Publican 2 in the dist-5E-epel-infra repo, or (better) build Publican 2 in Koji for dist-5E-epel-infra.

Dependencies not in el5

  • perl(Config::Simple) -- sixy
  • perl(DateTime::Format::DateParse) -- cweyl
  • perl(File::pushd) -- mmaslano * (built for EPEL -- need to push stable)
  • perl(Locale::PO) -- iarnell -- package change requested for EPEL
  • perl(Makefile::Parser) -- nb
  • perl(Syntax::Highlight::Engine::Kate) -- mmaslano
  • fop -- langel/lkundrak * (branched for EPEL -- need to build)
  • batik -- langel

Dependencies to update in el5

  • perl(XML::LibXML)
  • perl(XML::LibXSLT)
  • perl(XML::TreeBuilder)
  • docbook-style-xsl

Configure an Publican-generated website on the webserver

Publican can automatically generate its own website structure on the server. This consists of:

  • a configuration file at /etc/publican-website.cfg
  • an SQLite database at /var/lib/publican/publican-website.db
  • the /var/www/html/docs directory in which Publican publishes documentation would need to point to /var/www/html/docs on the server.

Desirable extra

It would be useful for the Documentation workflow to have a staging site available for viewing and proofreading test builds of documentation, at a permanent home on a public test machine. This machine would also need to run Publican 2.

Set up a build system for documents

To build documentation packages for (and a staging site), members of the docs-writers group need to be able to build packages and place them in a repo accessible by the web servers.

We need to explore:

  • could these packages be built for dist-5E-epel-infra? Ideally we would need separate subtags for documents destined for public consumption and those that will only appear on the stage. Members of the docs-writers group would be able to build any docs package and would be able to tag it for the stage; members of the docs-publishers group would additionally be able to tag any docs package for the public site.
  • could these packages be built on or will we need a separate Koji instance? The biggest issue here is not technical, but procedural, since the current package approval mechanism or packager approval mechanism are not a good fit for the docs project workflow. Since each document package is specific to a particular Fedora release, and since each language is packaged separately, we would have generated 101 new packages for Fedora 13, and needed to grant packager permissions to every member of the Docs team and Localization team working on these packages. It is unlikely that the current review process has the bandwidth to handle this number of new packages every release in a timely fashion; furthermore, since the packages are produced by Publican in a completely automated fashion, it is unlikely that most writers or translators will possess (or will ever possess) the knowledge required to gain packager permissions (but nor do they need this knowledge to build docs packages).

The future

It appears that Publican will ship with Red Hat Enterprise Linux 6, although the version of Publican in the Beta is a late version of Publican 1, which lacks the web publishing components. If Publican 2 ships with Red Hat Enterprise Linux 6, and if can be hosted on a server that runs Red Hat Enterprise Linux 6, we will no longer need to maintain Publican and its dependencies in dist-5E-epel-infra.