No edit summary |
|||
(17 intermediate revisions by the same user not shown) | |||
Line 20: | Line 20: | ||
To install Publican 4.0 on the webserver, we need to | To install Publican 4.0 on the webserver, we need to | ||
* <s>get a new el6-docs build root -- [https://fedorahosted.org/rel-eng/ticket/5214 rel-eng request here]</s> Done! Thanks ausil! | * <s>get a new el6-docs build root -- [https://fedorahosted.org/rel-eng/ticket/5214 rel-eng request here]</s> Done! Thanks ausil! | ||
* identify and build any dependencies not in el6 for EPEL | * <s>identify and build any dependencies not in el6 for EPEL</s> | ||
* identify and build any dependencies too old or not on all arches in el6 for el6-docs. | * <s>identify and build any dependencies too old or not on all arches in el6 for el6-docs.</s> | ||
* build Publican 4.0 and the Fedora brand package for el6-docs. | * build <s>Publican 4.0 and</s> the Fedora brand package for el6-docs. | ||
====Dependencies not in el6==== | ====Dependencies not in el6==== | ||
* <s>wkhtmltopdf</s> | * <s>wkhtmltopdf</s> | ||
** <s>wkhtmltopdf-qt</s> | ** <s>wkhtmltopdf-qt</s> | ||
* <s>perl-DateTime-Format-DateParse</s> | * <s>perl-DateTime-Format-DateParse</s> | ||
* perl-Locale-Msgfmt | * <s>perl-Locale-Msgfmt (branch requested for EPEL)</s> | ||
* perl-Lingua-EN-Fathom | * <s>perl-Lingua-EN-Fathom (coming in EPEL)</s> | ||
* | * <s>perl-XML-Catalog (for XML::TreeBuilder, coming in EPEL)</s> | ||
* <s>perl-IO-Compress</s> | |||
** <s>perl-Compress-Raw-Bzip2</s> | |||
** <s>perl-Compress-Raw-Zlib</s> | |||
====Dependencies to update in el6==== | ====Dependencies to update in el6==== | ||
* <s>perl-HTML-Tree -- too old</s> | * <s>perl-HTML-Tree -- too old</s> | ||
** perl-XML-TreeBuilder -- too old | ** <s>perl-XML-TreeBuilder -- too old</s> | ||
* docbook5-style-xsl -- too old | * <s>docbook5-style-xsl -- too old</s> | ||
* perl-Archive-Tar -- too old | * <s>perl-Archive-Tar -- too old</s> | ||
* perl- | * <s>perl-Syntax-Highlight-Engine-Kate -- too old</s> | ||
** <s>perl-Test-Differences (for Syntax-Highlighting-Kate) -- too old</s> | |||
<!-- | <!-- | ||
Line 46: | Line 48: | ||
The EL5 version of Publican 2 depends on fonts-chinese-zysong, which is shipped only on the Red Hat Enterprise Linux 5 supplementary CD due to licensing reasons.[https://rhn.redhat.com/errata/RHEA-2007-0833.html] Since we won't be able to build fonts-chinese-zysong in Koji, we will need to find a way to work around this dependency. It would mean modification to (at least) the Publican spec file, and the pdf.xsl file that ships with Publican. | The EL5 version of Publican 2 depends on fonts-chinese-zysong, which is shipped only on the Red Hat Enterprise Linux 5 supplementary CD due to licensing reasons.[https://rhn.redhat.com/errata/RHEA-2007-0833.html] Since we won't be able to build fonts-chinese-zysong in Koji, we will need to find a way to work around this dependency. It would mean modification to (at least) the Publican spec file, and the pdf.xsl file that ships with Publican. | ||
--> | --> | ||
===Update the Fedora brand=== | |||
The Fedora brand needs some minor updates to make it Publican 4 ready. Probably just book titles in HTML, and renaming a CSS file for the -web subpackage. | |||
* needs fonts-overpass to go stable in EPEL (requested) | |||
===Configure an Publican-generated website on the webserver=== | ===Configure an Publican-generated website on the webserver=== | ||
Line 73: | Line 80: | ||
We would need a target/tag for dist-6E-docs and perms for docs project members to build in there | We would need a target/tag for dist-6E-docs and perms for docs project members to build in there | ||
--> | --> | ||
===Contents of el6-docs=== | |||
As a footnote, these are the packages we are carrying in el6-docs. Ones marked in bold can (and should) be carried in EPEL itself -- we're working on this! | |||
* docbook-style-xsl-1.78.1-2.el6 | |||
* '''perl-HTML-FormatText-WithLinks-0.14-9.el6''' | |||
* '''perl-HTML-FormatText-WithLinks-AndTables-0.02-5.el6''' | |||
* wkhtmltopdf-qt-4.8.0-6.git20111107.el6 | |||
* wkhtmltopdf-0.10.0_rc2-8.el6 | |||
* perl-HTML-Tree-4.2-1.el6 | |||
* '''perl-Locale-Msgfmt-0.15-9.el6''' | |||
* docbook5-style-xsl-1.78.1-2.el6 | |||
* perl-Archive-Tar-1.92-4.el6 | |||
* perl-XML-TreeBuilder-5.1-0.el6 | |||
* perl-Test-Differences-0.5000-11.el6 | |||
* perl-Syntax-Highlight-Engine-Kate-0.08-4.el6 | |||
* perl-Compress-Raw-Bzip2-2.062-2.el6 | |||
* perl-Compress-Raw-Zlib-2.062-2.el6 | |||
* perl-IO-Compress-2.062-2.15.el6 | |||
* publican-4.0.0-0.el6 | |||
[[Category:Docs Project]] | [[Category:Docs Project]] |
Latest revision as of 00:29, 4 February 2014
This page tracks progress towards implementing a fully automated publishing process for the Fedora Documentation Project.
Background
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 maintains the Fedora documentation site (docs.fedoraproject.org) and automatically generates and updates the navigation menus in each language.
At present, the entire documentation suite hosted at http://docs.fedoraproject.org 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 6, the documentation packages need to be built for Red Hat Enterprise Linux 6. 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 4.0 on the webserver
The version of Publican shipped in Red Hat Enterprise Linux 6 is very old (2.1) and lacks many bug fixes and enhancements that have been added since then (current upstream is 4.0, due in Fedora in the next few weeks).
Some of the Publican 4.0 deps in Red Hat Enterprise Linux 6 are too old or not available on all arches; we will need to build these for el6-docs
It's also possible that Publican 4.0 has dependencies that are not in Red Hat Enterprise Linux 6; at all. If so, we will need to add these to EPEL.
To install Publican 4.0 on the webserver, we need to
get a new el6-docs build root -- rel-eng request hereDone! Thanks ausil!identify and build any dependencies not in el6 for EPELidentify and build any dependencies too old or not on all arches in el6 for el6-docs.- build
Publican 4.0 andthe Fedora brand package for el6-docs.
Dependencies not in el6
wkhtmltopdfwkhtmltopdf-qt
perl-DateTime-Format-DateParseperl-Locale-Msgfmt (branch requested for EPEL)perl-Lingua-EN-Fathom (coming in EPEL)perl-XML-Catalog (for XML::TreeBuilder, coming in EPEL)perl-IO-Compressperl-Compress-Raw-Bzip2perl-Compress-Raw-Zlib
Dependencies to update in el6
perl-HTML-Tree -- too oldperl-XML-TreeBuilder -- too old
docbook5-style-xsl -- too oldperl-Archive-Tar -- too oldperl-Syntax-Highlight-Engine-Kate -- too oldperl-Test-Differences (for Syntax-Highlighting-Kate) -- too old
Update the Fedora brand
The Fedora brand needs some minor updates to make it Publican 4 ready. Probably just book titles in HTML, and renaming a CSS file for the -web subpackage.
- needs fonts-overpass to go stable in EPEL (requested)
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
Set up webserver for automatic updates
The webserver should check the el6-docs repo on a cronjob to look for new, updated, or deleted packages. Rudi can supply a script for this.
Build the docs packages
As a team, we would need to build all the docs packages in Koji. I think as long as we do all packages for F19 and F20, we can proceed to the next step (cutover) and gradually rebuild our legacy docs over a longer period of time.
Cutover
When the documentation for currently maintained versions (F19 and F20) has all been rebuilt, we request that Infra points
docs.fedoraproject.org to /var/www/html/docs on the server.
Contents of el6-docs
As a footnote, these are the packages we are carrying in el6-docs. Ones marked in bold can (and should) be carried in EPEL itself -- we're working on this!
- docbook-style-xsl-1.78.1-2.el6
- perl-HTML-FormatText-WithLinks-0.14-9.el6
- perl-HTML-FormatText-WithLinks-AndTables-0.02-5.el6
- wkhtmltopdf-qt-4.8.0-6.git20111107.el6
- wkhtmltopdf-0.10.0_rc2-8.el6
- perl-HTML-Tree-4.2-1.el6
- perl-Locale-Msgfmt-0.15-9.el6
- docbook5-style-xsl-1.78.1-2.el6
- perl-Archive-Tar-1.92-4.el6
- perl-XML-TreeBuilder-5.1-0.el6
- perl-Test-Differences-0.5000-11.el6
- perl-Syntax-Highlight-Engine-Kate-0.08-4.el6
- perl-Compress-Raw-Bzip2-2.062-2.el6
- perl-Compress-Raw-Zlib-2.062-2.el6
- perl-IO-Compress-2.062-2.15.el6
- publican-4.0.0-0.el6