Roundcube Webmail Online Help

The repo contains the sources to generate the online help files documenting the functions of Roundcube Webmail for end users.

The documentation is based on the Sphinx Documentation Generator and source files are written in reStructuredText (reST). The designated output format is HTML.

Generating Help Files

First of all you need Python and Sphinx installed. Grab the latest version of Sphinx with

sudo easy_install -U Sphinx

Alteratively you can use a container image. Have a look at install-deps-in-sphinx-container.sh.

This repo already contains the Sphinx project configuration and can be generated right away with the following command:

cd <this-repo-checkout-dir>
make html

The above example generates the English (US) online help files with English localization for the navigation into the build/html/en_US output directory.

To generate the pages for all available languages and produce the document tree that is served on https://docs.roundcube.net, run:

make pages

This builds the document tree in the pages directory.

Integrating Help for Plugins

For adding help contents from plugins to the table of contents, index and search pages you can place doc files from plugins into the <lang>/plugins folder. All the resources for plugin docs need to reside in a dedicated folder for the plugin which at least contains an index.rst with the TOC of the plugin help. Here's an example folder structure:

en_US/
    _plugins/
        <plugin-A>
            _static/screenshot.png
            index.rst
            moredoc.rst
        <plugin-B>
            index.rst

Translating

Volunteers who want to help translating the online help files into another language, please apply for a team membership at our Transifex project and start translating online.

Using Transifex is really easy. Should you still have problems to understand one thing or the other, the Transifex Translator Guide might help you to get up to speed more quickly.

Generating Translated Files

1. Pull translated .po files from Transifex, for example for the French language:

   tx pull -f -l fr
   

2. Run Sphinx to build the localized docs by using the LANGUAGE parameter:

   make LANGUAGE=fr html
   

   (Note: do not specify a 5-character locale here, it won't work.)

Adding languages

To add a language to the list of generated pages, follow these steps:

1. Add a section to the Makefile.
2. Add the language to the pages target in the Makefile.
3. Add a link to source/_static/generic-index.html

Skins Support

When using screen shots in the help documents, they should match the skin used in the webmail application. Therefore, all _static directories containing images have subdirectories for skins (e.g. larry) and a symlink _skin pointing to the skin you want to use for rendering the docs.

For easily changing these, have a look at the setskin.sh utility script which updates all _skin symlinks it finds in the project directory.

License

All contents published under the Creative Commons Attribution-ShareAlike license. You are free to

• Share — to copy, distribute and transmit the work
• Remix — to adapt the work
• make commercial use of the work

under the conditions that

• you must attribute the work by mentioning the original source and authors
• if you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.