diff --git a/README.rst b/README.rst index f1a5aec4f..b77a87c64 100644 --- a/README.rst +++ b/README.rst @@ -2,133 +2,53 @@ End-user Odoo documentation =========================== -Building requirements: +Build the documentation +======================= -* Python 2.7 -* recent `Sphinx `_ (at least Sphinx 1.2) +Requirements +------------ - you can check if Sphinx is installed by trying to launch +- `Git `_ - .. code-block:: console +- | `Python 3 `_ + | If you don't know which subversion to choose, pick the last one. + | Python dependencies are listed in the file ``requirements.txt`` located in the root + directory. - $ sphinx-build --version + - Sphinx 2.4.0 or above. + - Werkzeug 0.14.1 - 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 `_ - .. code-block:: console +Instructions +------------ - $ make html +In a terminal, navigate to the root directory and execute the following command: - this should compile the documentation to HTML, and put the generated - HTML in ``_build/html/index.html``. +.. code-block:: console -Contributions -============= + $ make html -For simple edition (typo, just add paragraphs of text without markup), -the Github web interface can be used directly. +This compiles the documentation to HTML. -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. +Open ``documentation-user/_build/html/index.html`` in your web browser to display the render. -Issues can be reported on the repository's bug tracker as usual. +See `this guide +`_ +for more detailed instructions. -Custom features -=============== +Contribute to the documentation +=============================== -Extensions ----------- - -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``. - - .. code-block:: restructuredtext - - .. 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: - - .. code-block:: restructuredtext - - .. demo:action:: account_asset.action_account_asset_asset_list_normal_sale - - View *Asset Types* - -Theme Customisations --------------------- - -* 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 - - .. code-block:: restructuredtext - - :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 - `_. - - - -Importing existing documents -============================ - -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. +For contributions to the content of the documentation, please refer to the `Introduction Guide +`_. +To **report a content issue**, **request new content** or **ask a question**, use the `repository's +issue tracker `_ as usual. Learn More ========== -To learn more about Odoo, in addition to the documentation, have a look at the official -`eLearning `_ and `Scale-up, The Business Game `_ +To learn more about Odoo, in addition to the documentation, have a look at `the official eLearning +`_ and `Scale-up, The Business Game +`_ \ No newline at end of file diff --git a/contributing/documentation/rst_cheat_sheet.rst b/contributing/documentation/rst_cheat_sheet.rst index d391d363d..7816dbdd9 100644 --- a/contributing/documentation/rst_cheat_sheet.rst +++ b/contributing/documentation/rst_cheat_sheet.rst @@ -468,6 +468,19 @@ Render Formatting tips =============== +.. _contributing/banners: + +Add banners on top of documents +------------------------------- + +.. raw:: html + + Odoo feature + +The Odoo theme supports banner images at the top of documents. At the first line of your documents, +insert the directive ``:banner: banners/file_name.png``. Replace ``file_name.png`` with the file +that you placed in :file:`_static/banners` to server as a banner of your document. + .. _contributing/line-break: Break the line but not the paragraph