文档处理

书籍

The main documentation of OpenERP is composed of a set of books according to the business need. These books are reviewed once a year. We are working with authors/contributors/employees/translators to build chapters on the different aspects of the ERP.

This section describes how we collaborate with authors and translators to provide very good documentation on OpenERP. To motivate people to write quality documentation/chapters we set up author rights to pay each contributor and translator according to their effort.

创建数据

We have contracts with several editors to publish books in different countries.

Once we have enough chapters written, we can compose a book and publish it.

Books are first published in a paper version. Three months after, we release it online.

著作权

The typical author rights are between 8% and 10% on the public price, according to the authors, the country and the editor in which the book will be published. This commission is on the public price, no matter of the final selling price per item.

These author rights have to be divided according to people working on the book:

  • Reviewers: 10% to be divided by number of reviewers
  • Translators: 30% to be divided by the number of translators
  • Authors: the rest (60%-90%) to be divided by number of authors

As an example, Geoff and Fabien worked on the French and English book on OpenERP. This book is sold at a public price of 35 EUR with 10% author rights. We had one reviewer for this book from Eyrolles. So author rights are split in that way:

  • Geoff: 1.575 EUR/book (= 35 * 0.1 * (0.9 / 2))
  • Fabien: 1.575 EUR/book
  • Reviewer: 0.35 EUR/book (= 35 * 0.1 * 0.1)

Once this book will be translated to Hungarian, with a public price of 30 EUR and author rights of 10% (0.1) we will have:

  • Geoff: 1.05 EUR/book (=30 * 0.1 * 0.7 / 2)
  • Fabien: 1.05 EUR/book
  • Hungarian translator: 0.90 EUR/book (=30 * 0.1 * 0.30)

Author rights are paid every 3 months, after one month. (to be verified according to what we can do with editors)

个人

作者

Anyone can be an author and write a complete book or just one or several chapters on particular aspects of OpenERP. Chapters are then review

来自 Tiny 的作者

At Tiny (the editor of OpenERP), each employee can write a few chapters based on new module he wrote for specific customers, at the end of the project. As employees get a salary to write these chapters during their working hours, author rights are computed slightly differently:

  • Computed rights are divided by two for the employee: 50%
  • Valid while the employee works for Tiny

建立文档

文档能从下面的源里下载到:

bzr branch lp:openobject-doc

我们使用 Sphinx, 一个用来建立文档的生成器, 因此，将被安装在你的系统里。 你后面将了解如何使用它.

You can install it with easy_install. For example, on Ubuntu:

sudo easy_install sphinx

Sphinx is built on top of the reStructuredText project that lets you write documents in plain text files and then generate HTML, PDF or other formats from them. A good introduction to reStructuredText is the Quick reStructuredText reference page. reStructuredText defines the layout and formatting of a single page. Sphinx lets you organise several pages into a large document with a table of contents and cross references.

Note

if you step into this error message (line number can vary):

! Undefined control sequence.
l.462 \capstart

This sometimes means that you have a buggy version of sphinx. Try to install Sphinx version 1.0.2:

sudo easy_install sphinx==1.0.2 --upgrade

Building the documentation in HTML and in PDF requires a few dependencies, namely for the LaTeX system (additional packages and fonts). On Ubuntu you can install the required packages with the following command::

# Install Latex extras
sudo apt-get install texlive-latex-extra texlive-fonts-recommended
# Install ImageMagick for images conversion
sudo apt-get install imagemagick
building the documentation in html:
make clean
make html
building the documentation in pdf:
make clean
make latex
cd build/latex
make all-pdf
building a book:

For example, if you want to build the OpenERP for Retail and Industrial Management book:

cd books/book_mrp
make clean
make latex
cd build/latex
make all-pdf

链接到源码的文档

Some of the pages include links to classes in the project’s source code. One example is developer/2_5_Objects_Fields_Methods/methods.rst. You can add more links to source code documentation using the Sphinx autodoc extension. This will import classes and methods along with their docstring documentation. If you don’t tell Sphinx how to find the project’s source code, then the import will fail with a warning. If you want to make the import work, follow these steps:

  1. It seems like you need at least version 1.0 of Sphinx. If your version hasn’t automatically upgraded that far, see the easy_install instructions above. To see what version you have, run the following:

    sphinx-build --help

  2. You need to have a copy of the OpenERP server code. The web site builds against the trunk version.

  3. You need to tweak server/bin/tools/config.py by commenting out the call to config.parse_config() on the last line. Hopefully that will get cleaned up eventually, but for now you either need a second copy of the server just for building the docs from or you need to add and remove this tweak every time you work on the docs.

  4. You need to add server/bin to your PYTHONPATH environment variable. The simplest way to do that is to launch make like this:

    PYTHONPATH=/path/to/server/bin make html

FAQ

How many units can we expect to sell for a book ?

Our first French book sold 500 units per month. It’s good as it was our the first book on OpenERP but we can expect better results with an English version. So probably between 250 and 1500 units per month for an English book.