No edit summary |
|||
| Line 8: | Line 8: | ||
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. [http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/sect-Users_Guide-Website.html Chapter 6 of the ''Publican Users' Guide''] provides an overview of the mechanism. | 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. [http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/sect-Users_Guide-Website.html Chapter 6 of the ''Publican Users' Guide''] provides an overview of the mechanism. | ||
'''Important''' -- note that since the webserver runs Red Hat Enterprise Linux | '''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== | ==Steps to automate publishing== | ||
===Install Publican 2 on the webserver=== | ===Install Publican 2 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 and Fedora is 2.8). | |||
Publican 2.8 has a number of dependencies that are not in Red Hat Enterprise Linux 6; we will need to add these to EPEL. (It's also possible that some of the deps in Red Hat Enterprise Linux 6 are too old; we will need to investigate this). | |||
To install Publican 2.8 on the webserver, we need to | |||
* | * get a new dist-6E-epel-infra build root | ||
* identify and build any dependencies not in el6 for EPEL | |||
* | * identify and build any dependencies too old in el6 for dist-6E-epel-infra. | ||
* build Publican 2.8 and the Fedora brand package for dist-6E-epel-infra. | |||
* | |||
* | |||
====Dependencies | ====Dependencies not in el6==== | ||
====Dependencies to update in el6==== | |||
<!-- | |||
====fonts-chinese-zysong==== | ====fonts-chinese-zysong==== | ||
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. | ||
--> | |||
===Configure an Publican-generated website on the webserver=== | ===Configure an Publican-generated website on the webserver=== | ||
| Line 70: | Line 43: | ||
Documentation also has a stage at http://docs.stg.fedoraproject.org. This host should also have Publican 2 running on it so that we can stage documents there that are not yet ready for even the "drafts" section of the main docs site. The most important use case would be the nightly builds of translated documentation that the Documentation project produces for the Localization project in the last few weeks before a release. Besides this, however, writers sometimes want to share extremely embryonic documentation. Being able to do this through the automated packaging system keeps even these early stages of development inside the main docs workflow. | Documentation also has a stage at http://docs.stg.fedoraproject.org. This host should also have Publican 2 running on it so that we can stage documents there that are not yet ready for even the "drafts" section of the main docs site. The most important use case would be the nightly builds of translated documentation that the Documentation project produces for the Localization project in the last few weeks before a release. Besides this, however, writers sometimes want to share extremely embryonic documentation. Being able to do this through the automated packaging system keeps even these early stages of development inside the main docs workflow. | ||
===Set up | ===Set up Koji for documents=== | ||
We would need a target/tag for dist-6E-docs and perms for docs project members to build in there | |||
[[Category:Docs Project]] | [[Category:Docs Project]] | ||
Revision as of 02:24, 19 June 2012
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 2 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 and Fedora is 2.8).
Publican 2.8 has a number of dependencies that are not in Red Hat Enterprise Linux 6; we will need to add these to EPEL. (It's also possible that some of the deps in Red Hat Enterprise Linux 6 are too old; we will need to investigate this).
To install Publican 2.8 on the webserver, we need to
- get a new dist-6E-epel-infra build root
- identify and build any dependencies not in el6 for EPEL
- identify and build any dependencies too old in el6 for dist-6E-epel-infra.
- build Publican 2.8 and the Fedora brand package for dist-6E-epel-infra.
Dependencies not in el6
Dependencies to update in el6
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
docs.fedoraproject.org would need to point to /var/www/html/docs on the server.
Staging site
Documentation also has a stage at http://docs.stg.fedoraproject.org. This host should also have Publican 2 running on it so that we can stage documents there that are not yet ready for even the "drafts" section of the main docs site. The most important use case would be the nightly builds of translated documentation that the Documentation project produces for the Localization project in the last few weeks before a release. Besides this, however, writers sometimes want to share extremely embryonic documentation. Being able to do this through the automated packaging system keeps even these early stages of development inside the main docs workflow.
Set up Koji for documents
We would need a target/tag for dist-6E-docs and perms for docs project members to build in there