Building requirements:

• Python 2.7

• recent Sphinx (at least Sphinx 1.2)

  you can check if Sphinx is installed by trying to launch

  $ sphinx-build --version

  See the sphinx documentation for local installation instructions.

• git

• clone this repository using git, then at the root of the repository, in a console,

  $ make html

  this should compile the documentation to HTML, and put the generated HTML in _build/html/index.html.

For simple edition (typo, just add paragraphs of text without markup), the Github web interface can be used directly.

For more complex edition, to add images or advanced directives, edit locally. Do not commit if there are warnings or errors when building the documentation fix them first. rST is fairly sensitive to whitespace and newlines (especially the lack of newlines). It's a bit annoying but it's not hard to learn.

Issues can be reported on the repository's bug tracker as usual.

Two custom directives are provided for integration with Odoo's demo system:

• demo:fields:: {external_id} lists all the fields with a tooltip (help) of the action whose external_id is provided.

  • Uses the form view by default, can be customized by specifying :view:.
  • The list of fields displayed can be filtered with :only: which should be a list of space-separated fields to display. Note that this will further reduce the number of fields displayed, it will not force fields to be listed when they don't have a help.

  .. demo:fields:: account_asset.action_account_asset_asset_list_normal_sale
     :only: name

  will display a table of just the name field and its help (or nothing if the name field does not have a help)

• demo:action:: {external_id} will create a link button to the action (specified by external id) on the demo site. The text of the button should be provided as the directive's content:

  .. demo:action:: account_asset.action_account_asset_asset_list_normal_sale
  
     View *Asset Types*

• The Odoo theme supports Banner Images at the top of documents. These banners are configured by setting a :banner: field at the top of the document (before the page title), the banner images will be looked up in the _static folder at the root of the project

  :banner: banners/accounting.png
  
  ==========
  Accounting
  ==========
  
  [...]

  Warning

  because banners are wide images and each page may have one, it is strongly recommended to compress them well. For PNG, use pngquant (or a UI to it) to reduce the number of colors in the image followed by regular PNG recompression tools like pngcrush and pngout.

For documents which already exist in an other format or in Google docs, it's possible to get a head-start by converting the existing document using Pandoc. The main issue is that anything but trivial original documents will need fixing up (possibly lots of it) to get good rST (or possibly working rST at all).

Example:

pandoc -f docx -t rst path/to/document.docx -o new_doc.rst --extract-media=.

will convert path/to/document.docx to new_doc.rst and export all images to ./media (and link them from the document). While there are issues with the exported document, it's much more convenient than manually re-typing the original.