SimplifyUbuntuDocsBuildProcess

Summary

We would like to improve the build system for the documentation repository, to ensure that everything necessary to get the documentation validated, translated and uploaded is simple and well documented.

Rationale

Currently, the process for getting Ubuntu documentation validated, translated and uploaded involves a significant amount of manual intervention. This in turn leads to a certain amount of dependency on the people who know what needs to be done, and occasionally to things being overlooked. For example, during the Edgy release cycle MatthewEast, RichardJohnson and DanielHolbach had to spend a non-trivial amount of time polishing the build system and manually adding translations. This should not be necessary.

Use Cases

  • Matthew is a docteam member. He would like to write some documentation but finds his spare time is taken up with generating translation templates, importing translations and manually adding them to the packaging.
  • Daniel is an Ubuntu developer. He would like to work on some awesome desktop features but has to waste time fixing Matthew's mistakes.
  • Carlos is an Ubuntu translator. He would like to be able to be certain that all necessary components of the documentation are available in Rosetta for translation.

Scope

The documentation team svn repository.

Design

Some nice build features exist already in the repository. For example, the validate.sh script can be used to validate a document, the translate.sh scripts serve to convert translations downloaded from Rosetta into docbook. We need a central build process which can pull these things together.

We need:

  • A simple way to determine which documents are active and should go into the shipped documentation. For those documents, the build system should then be able to automatically:
    • Add the documents to the ubuntu-docs, kubuntu-docs and xubuntu-docs packaging.
    • Build a translation template for each document added to the package.
    • Import translations downloaded from Rosetta
    • Add translated documents to the ubuntu-docs, kubuntu-docs and xubuntu-docs packaging.

The following commands might be used from the top directory of the repository:

  • make translation-template documentname lang

  • make html documentname lang

  • make import-translations documentname lang

  • make web-html documentname lang

The possible values of documentname could be in a single file somewhere, so that changing that file would change the documents shipped in the ubuntu-docs packaging by way of a script in debian/rules.

lang should be optional - leaving it out would do the task for all languages.

Implementation

Not determined as yet.

Outstanding Issues

BoF agenda and discussion

CategorySpec

SimplifyUbuntuDocsBuildProcess (last edited 2008-08-06 16:22:40 by localhost)