odoo/doc
Xavier Morel 0aab81cd3a [IMP] doc: move manifest description from backend tutorial to manifest doc 2015-01-19 15:51:16 +01:00
..
_static [ADD] contribution files and image removed at 2ad092b 2014-10-02 12:05:32 +02:00
_themes/odoodoc [IMP] doc: simplify webservice api doc 2015-01-19 15:36:26 +01:00
howtos [IMP] doc: move manifest description from backend tutorial to manifest doc 2015-01-19 15:51:16 +01:00
images [IMP] doc: indexify index 2014-11-17 14:07:36 +01:00
reference [IMP] doc: move manifest description from backend tutorial to manifest doc 2015-01-19 15:51:16 +01:00
setup [ADD] doc: link to docker image 2015-01-16 11:58:38 +01:00
Makefile [IMP] doc/howtos/backend: small fixes 2014-08-29 08:42:35 +02:00
README.rst [FIX] doc readme: the list of versions uses commas 2014-09-29 13:40:10 +02:00
api_integration.rst [IMP] doc: title of api page 2015-01-15 10:55:48 +01:00
conf.py [CHG] doc: company officially renamed 2014-11-24 09:05:23 +01:00
git.rst [ADD] support for a version switcher in odoo theme thing 2014-09-04 14:43:55 +02:00
glossary.rst [ADD] doc: guide to the new API 2014-11-07 14:42:33 +01:00
index.rst [ADD] doc: setup documentation 2014-12-15 16:01:37 +01:00
reference.rst [IMP] doc: move translations to reference documentation 2014-12-02 09:40:59 +01:00
requirements.txt [ADD] documentation requirements 2014-12-22 14:48:15 +01:00
setup.rst [ADD] doc: setup documentation 2014-12-15 16:01:37 +01:00
tutorials.rst [IMP] wording and ordering of documentation index 2014-11-28 12:36:04 +01:00

README.rst

:orphan:

==================
Odoo Documentation
==================

Odoo Theme
==========

The Odoo Documentation theme is a bootstrap-based mix of http://odoo.com and
http://getbootstrap.com with additional changes and additions, bundled as
a Sphinx theme.

The main style file is ``_themes/odoodoc/static/style.less``, it is not
converted on the fly and must be compiled manually when altere, using the
official node-based lessc_ tool.

``odoodoc`` must be added as an extension to a project using the theme, it
fixes some discrepancies between bootstrap_ and Sphinx_ and adds a few
features:

Sphinx Customizations
---------------------

* toctree bullet lists (HTML ``<ul>``) are given the ``nav`` class
* the main navigation bar also gets the ``navbar-nav`` and ``navbar-right``
  set on its root (``navbar-right`` could probably be handled in CSS to avoid
  having it in the markup)
* tables are given the ``table`` class
* colspecs are removed from tables, tables should autolayout
* ``data-`` attributes are copied straight from the docutils node to the
  output HTML node
* an ``odoo`` pygments style based on the bootstrap_ documentation's
* the normal Sphinx sidebars are suppressed and a new sidebar is injected in
  ``div.document`` (``sidebar1`` is outside in the base Sphinx layout)
* HTML5 doctype

Additional features
-------------------

* versions switcher, uses the ``canonical_root`` setting and an additional
  ``versions`` setting which should be a comma-separated list of available
  versions. Appends the each version and page name to the root, and displays
  a list of those links on the current page
* canonical urls, requires a ``canonical_root`` setting value, and optionally
  a ``canonical_branch`` (default: ``master``)
* :guilabel:`Edit on github` link in Sphinx pages if ``github_user`` and
  ``github_project`` are provided
* :guilabel:`[source]` links in autodoc content links to github with the same
  requirements (requires Sphinx 1.2)
* ``aphorism`` class for admonitions, makes the first line of the admonition
  inline and the same size as the admonition category (mostly for short,
  single-phrase admonitions)
* ``exercise`` directive, mostly for training-type documents, the
  ``solutions`` tag_ can be used to conditionally show e.g. solutions
* a number of straight-to-HTML directives:

  ``h:div``
    a straight div, can be used instead of ``container`` (which adds the
    ``container`` class to the div it generates, that's really not compatible
    with Bootstrap_)
  ``h:address``
    generates an ``<address>`` node
  a bunch of roles straight to HTML inline
    ``mark``, ``insert``, ``delete``, ``strikethrough``, ``small`, ``kbd`` and
    ``var`` generate the corresponding HTML element

Requirements
------------

* Sphinx 1.1, 1.2 for code Python code links
* sphinx-patchqueue (for the content, not the theme)

.. _lessc: http://lesscss.org/#using-less
.. _bootstrap: http://getbootstrap.com
.. _sphinx: http://sphinx-doc.org
.. _tag: http://sphinx-doc.org/markup/misc.html#including-content-based-on-tags