The first one will open the documentation in a new tab in the application:

The second one will open the documentation in a PDF file that can later be printed. The content in both cases is exactly the same.

The last entry will open http://doc.openerp.com in a new tab in the application (press control key if you want it to be opened in your system's default browser):

As you can see. In the first and last options, the previous and next buttons (as well as reload) of the standard interface are used as the usual browser buttons. In fact, now URL actions are opened inside Koo by default (except if user presses the control key as already mentioned).

Even if what we have seen in the first option is what all of us are used when opening a manual it is hardly useful. If we wanted to read the whole manual we may print its PDF version, but that's it. Indeed, most usually we would find ourselves searching for information in it, like a field or a menu entry.

With the new framework, users will almost always open the manual using the new contextual interface. The idea is that users can view the parts of the manual that refer to the work they are doing at the moment. This has the advantage that documentation writers will write a single book with information structured as a book and that it can be read from the beginning until the end (like a book), but the documentation is ensured to be always useful because users will be directed to the sections they need when they need them.

The contextual interface is currently available in a couple places.

The one users will first notice is the new Help button we have added at the status bar. This will provide help for both menu entries:

in which you can see the paragraphs in the documentation where the reference to the menu appears, and views:

in which you can see the places that have screenshots of the view. In both cases, users can click and see the appropriate section in the documentation:

The second place in which we have added contextual information is in fields. Until now, only fields with a tip had a question mark in them. Now we have added the question mark to all fields (although those with a tip are shown in blue and those that don't have one are shown in black) and clicking on it displays not only the tip, but also all the places in the documentation where it is mentioned:

That's all we have implemented by now. Some other things we would like to introduce is being able to view the places where current state of the workflow of current document is mentioned so users can fully understand what open invoice means, for example.

Although this is all user-oriented, we also think the framework should be used to include developer information and integrators could add all notes and documentation generated during the integration process for a given customer.

Note that the documentation will only show information relevant for the modules that are currently installed and screenshots look like what the user has, so if the user is in a group that cannot see some fields, they will not appear in their screenshot even if it appears for the rest of the users.

Writing it

Structure

Each new module may have (hopefully we can make this a requirement) a doc directory and is written using Sphinx syntax plus some extensions (yes, you need Sphinx installed in the server). This ensures documentation is near the code and developers feel comfortable with it, while being intelligible by documentation writers too. So it is expected that the doc directory will have one or more .rst files. Alternatively, if the module provides documentation for other modules it could have a modules subdirectory with the documentation of each of the modules it documents (don't worry if you need to read this sentence twice, it occurred to me and I wrote it ;-). For example, as we (at NaN) have no commit access to addons repository, we have created some documentation for base, product and account modules. In this case, if the module is called addons_doc the directory will look like this:

addons_doc/doc/
addons_doc/doc/modules/
addons_doc/doc/modules/base/
addons_doc/doc/modules/product/
addons_doc/doc/modules/account/

Note that if a module provides documentation for other modules (and thus has the doc/modules/ directory) any other file inside doc/ will be just ignored. If we wanted to provide documentation for the addons_doc module itself, then we would add a new directory for it inside addons_doc/doc/modules.

I mentioned that the syntax of those files is Sphinx plus some extensions. There are two kinds of extension tags: replacements and identifiers.

Replacements

Replacements allow some information of the documentation to be filled in by content from the database the user is running. Currently the following three replacement types are implemented:

Fields

With the following syntax:

/// f: res.partner.name ///

It will replace the tag with the label of the field (Name in the example, with output in English). The reference to the field will be composed of the model and the field name separated with a dot. One can also print the help of the field with the following syntax:

/// f: res.partner.name : help ///

In both cases, the system will create an anchor just before the current paragraph, so the system will be able to find this occurrence of the field in the generated HTML.

Menus

With the following syntax:

/// m: base.menu_ir_sequence_form ///

It will replace the tag with the complete name of the menu (Administration/Configuration/Sequence/Sequence in the example, with output in English). The reference to the menu uses the model data that most developers are used to in view .xml files. This value is pretty easy to get in Koo by selecting the menu entry, clicking on switch view and then clicking on Plugins/Search Model Data menu on the top.

In this case, the system will also create an anchor just before the current paragraph, and in the future we will make it possible to open the menu entry from with the documentation itself.

Views

With the following syntax:

/// v: base.sequence_view ///

It will replace the tag with a screenshot of the view. In this case it would replace it with this image:

Like in menus, the reference follows the model data syntax, although one can add one modifier:

/// v: base.sequence_view : fiscal_ids ///

In this case, when the system will generate the screenshot, it will ensure the 'fiscal_ids' field it s shown even if it is not in the first tab. In this example, the image added would look like this:

This is interesting because we do not know how many tabs there will be when the documentation is rendered or the field we're talking about may have been moved to another place.

Also note that this feature does not disallow documentation writers the possibility of adding other screenshots or images. They should do that in the same way they would do with Sphinx and they will be properly rendered. The system will also ensure there are no collisions in filenames, so users should not worry about that either.

Example

With these explanations we can already understand a simple example that could serve as part of the documentation of the base module:

index.rst:

OpenERP Manual
==============

Contents:

.. toctree::
 :maxdepth: 2

  :numbered:

 base.rst

As you can see index.rst, tells Sphinx to load base.rst file which could look like this:

Configuration
=============

Sequences
---------

In /// m: base.menu_ir_sequence_form /// you can manage sequences which allow
advanced users to determine how document numbers will be generated.

/// v: base.sequence_view ///

Identifiers

They follow this syntax:

||| identifier_name_that I want |||
Here it starts the paragraph we want to have this identifier.

And they should go at the beginning of a paragraph (the paragraph itself should start at the next line or the next non-empty line).

Identifier tags allow giving each paragraph an ID, similar to what developers do with views, but in this case it is not required. If documentation writers do not provide an identifier for a paragraph, a default one will be created by the system automatically. To created it the system will use the first words of the paragraph (and a number if necessary) to ensure the ID is unique in its module.

Identifiers can also follow this syntax:

||| : after : base.base_rst |||
 product.rst

(in which the identifier of the paragraph will be created automatically) or this one:

||| add_product_rst : after : base.base_rst |||
 product.rst

In both cases we're telling the system to add the paragraph (which in this case simply contains ' product.rst') just after the paragraph with identifier base.base_rst. That is, the paragraph with ID base_rst in module base. If you take a look at the example above you will realize that here we're adding a new product.rst file to the index.rst file created by base module. As you may have guessed, the idea is that this documentation will be part of the product module.

The placement part of the identifier tag can currently be any of before, after (which will create new paragraphs, and thus add an empty line between the new paragraph and the inherited one), prepend, append (which will not create new paragraphs) and replace.

This inheritance mechanism gives great flexibility and allows avoiding the if's issue I mentioned in my last blog post, but as we need paragraphs as a reference, we should take this a little bit into account when writing documentation. For example, in Sphinx one can write a definition list like this:

word1
 explanation 1
word2
 explanation 2

or like this:

word1
 explanation 1

word2
 explanation 2

Both are correct in Sphinx and in this framework, but the latter gives more flexibility if someone writes a new module and needs to add a new entry between word1 and word2.

Because original identifiers can change over time if not set manually (due to the fact that the first words of the paragraph may be changed), we plan to allow the system to store the automatically generated IDs into original .rst files, so documentation writers can freely fix typos or restructure sentences without breaking documentation of other dependent modules and also freeing them of the task of having to create a unique ID per paragraph.

Apart from knowing a little bit of Sphinx, this is all you need to know to write documentation for this framework.

• In the case when the documentation writer is not the developer that created the module, they will need a way to easily indicate that the documentation they're writing is linked with the given module without the need of modifying the module itself. Even if the documentation should ideally be linked with the code in the same module, they need a way to make documentation for modules over which they do not have control (ie. commit rights).
• When documentation writers are not developers they will need a system that is usable by non-geeks.
• Creating screenshots is one of the worst issues to keep documentation up to date. If we add the fact that views vary depending on the modules installed and even on a per user basis (some users may have some fields that others don't) it seems to be almost impossible to have useful screenshots without a huge effort.
• It is complicated to keep up to date field names and menu entries in the documentation if they're changed by developers in the source code, so they need help here too.

• Keeping screenshots up to date. Yes, even if documentation writers were be able to create screenshots for all the cases we mentioned, translators would have to create them again for their own language.
• Using the exact same words for menu entries and field names that were used for translating the fields and menu entries that users see in the application.
• They need a translation system that lets them easily keep track of what was translated and what not. Doing a translation as if it was a single book that never evolves seems to be calling for problems in the near future for translators.