[MERGE] Forward-port of branch 12.0 to 13.0
This commit is contained in:
Antoine Vandevenne (anv)
commit
5b03c33afd
142
README.rst
142
README.rst
@ -2,133 +2,53 @@
|
||||
End-user Odoo documentation
|
||||
===========================
|
||||
|
||||
Building requirements:
|
||||
Build the documentation
|
||||
=======================
|
||||
|
||||
* Python 2.7
|
||||
* recent `Sphinx <http://sphinx-doc.org>`_ (at least Sphinx 1.2)
|
||||
Requirements
|
||||
------------
|
||||
|
||||
you can check if Sphinx is installed by trying to launch
|
||||
- `Git <https://www.odoo.com/documentation/user/contributing/documentation/introduction_guide.html#install-git>`_
|
||||
|
||||
.. code-block:: console
|
||||
- | `Python 3 <https://www.odoo.com/documentation/user/contributing/documentation/introduction_guide.html#python>`_
|
||||
| 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 <http://sphinx-doc.org/install.html>`_
|
||||
for local installation instructions.
|
||||
* `git <http://www.git-scm.com>`_
|
||||
* clone this repository using git, then at the root of the repository,
|
||||
in a console,
|
||||
- `Make <https://www.odoo.com/documentation/user/contributing/documentation/introduction_guide.html#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
|
||||
<https://www.odoo.com/documentation/user/contributing/documentation/introduction_guide.html#prepare-your-version>`_
|
||||
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 <https://pngquant.org>`_ (or a UI to it) to reduce the
|
||||
number of colors in the image followed by regular PNG
|
||||
recompression tools like `pngcrush
|
||||
<http://pmt.sourceforge.net/pngcrush/>`_ and `pngout
|
||||
<http://www.advsys.net/ken/util/pngout.htm>`_.
|
||||
|
||||
|
||||
|
||||
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 <http://pandoc.org>`_. 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
|
||||
<https://www.odoo.com/documentation/user/contributing/documentation/introduction_guide.html>`_.
|
||||
|
||||
To **report a content issue**, **request new content** or **ask a question**, use the `repository's
|
||||
issue tracker <https://github.com/odoo/documentation-user/issues>`_ as usual.
|
||||
|
||||
Learn More
|
||||
==========
|
||||
|
||||
To learn more about Odoo, in addition to the documentation, have a look at the official
|
||||
`eLearning <https://odoo.com/slides>`_ and `Scale-up, The Business Game <https://www.odoo.com/page/scale-up-business-game>`_
|
||||
To learn more about Odoo, in addition to the documentation, have a look at `the official eLearning
|
||||
<https://odoo.com/slides>`_ and `Scale-up, The Business Game
|
||||
<https://www.odoo.com/page/scale-up-business-game>`_
|
||||
@ -468,6 +468,19 @@ Render
|
||||
Formatting tips
|
||||
===============
|
||||
|
||||
.. _contributing/banners:
|
||||
|
||||
Add banners on top of documents
|
||||
-------------------------------
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<span class="badge" style="background-color:#AD5E99">Odoo feature</span>
|
||||
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user