Albert Cervera i Areny Aug 28, 2010
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.
/// 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.
/// 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:
/// 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.
OpenERP Manual ============== Contents: .. toctree:: :maxdepth: 2
:numbered: base.rstAs 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 ///
||| 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.rstIn 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 2or like this:
word1 explanation 1 word2 explanation 2Both 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.