[IMP] README: update README and refer to contributing/documentation
This commit is contained in:
Antoine Vandevenne (anv)
parent
950b460794
commit
f08b5da17f
134
README.rst
134
README.rst
@ -2,126 +2,44 @@
|
|||||||
End-user Odoo documentation
|
End-user Odoo documentation
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
Building requirements:
|
Build the documentation
|
||||||
|
=======================
|
||||||
|
|
||||||
* Python 2.7
|
Requirements
|
||||||
* recent `Sphinx <http://sphinx-doc.org>`_ (at least Sphinx 1.2)
|
------------
|
||||||
|
|
||||||
you can check if Sphinx is installed by trying to launch
|
- :ref:`Git <contributing/install-git>`
|
||||||
|
|
||||||
.. code-block:: console
|
- | :ref:`Python 3 <contributing/python>`
|
||||||
|
| If you don't know which subversion to choose, pick the last one.
|
||||||
|
| Python dependencies are listed in the file :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>`_
|
- :ref:`Make <contributing/make>`
|
||||||
for local installation instructions.
|
|
||||||
* `git <http://www.git-scm.com>`_
|
Instructions
|
||||||
* clone this repository using git, then at the root of the repository,
|
------------
|
||||||
in a console,
|
|
||||||
|
In a terminal, navigate to the root directory and execute the following command:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
$ make html
|
$ make html
|
||||||
|
|
||||||
this should compile the documentation to HTML, and put the generated
|
This compiles the documentation to HTML.
|
||||||
HTML in ``_build/html/index.html``.
|
|
||||||
|
|
||||||
Contributions
|
Open :file:`_build/html/index.html` in your web browser to display the render.
|
||||||
=============
|
|
||||||
|
|
||||||
For simple edition (typo, just add paragraphs of text without markup),
|
See :ref:`contributing/prepare-version` for more detailed instructions.
|
||||||
the Github web interface can be used directly.
|
|
||||||
|
|
||||||
For more complex edition, to add images or advanced directives, edit
|
Contribute to the documentation
|
||||||
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.
|
For contributions to the content of the documentation, please refer to
|
||||||
|
:doc:`contributing/documentation/introduction_guide`.
|
||||||
|
|
||||||
Custom features
|
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.
|
||||||
|
|
||||||
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.
|
|
||||||
@ -468,6 +468,19 @@ Render
|
|||||||
Formatting tips
|
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:
|
.. _contributing/line-break:
|
||||||
|
|
||||||
Break the line but not the paragraph
|
Break the line but not the paragraph
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user