[IMP] README: update README and refer to contributing/documentation
This commit is contained in:
Antoine Vandevenne (anv)
parent
b109c3afa1
commit
ce6785d158
134
README.rst
134
README.rst
@ -2,126 +2,44 @@
|
||||
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
|
||||
- :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>`_
|
||||
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,
|
||||
- :ref:`Make <contributing/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 :file:`_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 :ref:`contributing/prepare-version` for more detailed instructions.
|
||||
|
||||
Custom features
|
||||
===============
|
||||
Contribute to the documentation
|
||||
===============================
|
||||
|
||||
Extensions
|
||||
----------
|
||||
For contributions to the content of the documentation, please refer to
|
||||
:doc:`contributing/documentation/introduction_guide`.
|
||||
|
||||
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.
|
||||
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.
|
||||
@ -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