doc/README.rst

   1 :orphan:
   2
   3 ==================
   4 Odoo Documentation
   5 ==================
   6
   7 Odoo Theme
   8 ==========
   9
  10 The Odoo Documentation theme is a bootstrap-based mix of http://odoo.com and
  11 http://getbootstrap.com with additional changes and additions, bundled as
  12 a Sphinx theme.
  13
  14 The main style file is ``_themes/odoodoc/static/style.less``, it is not
  15 converted on the fly and must be compiled manually when altere, using the
  16 official node-based lessc_ tool.
  17
  18 ``odoodoc`` must be added as an extension to a project using the theme, it
  19 fixes some discrepancies between bootstrap_ and Sphinx_ and adds a few
  20 features:
  21
  22 Sphinx Customizations
  23 ---------------------
  24
  25 * toctree bullet lists (HTML ``<ul>``) are given the ``nav`` class
  26 * the main navigation bar also gets the ``navbar-nav`` and ``navbar-right``
  27   set on its root (``navbar-right`` could probably be handled in CSS to avoid
  28   having it in the markup)
  29 * tables are given the ``table`` class
  30 * colspecs are removed from tables, tables should autolayout
  31 * ``data-`` attributes are copied straight from the docutils node to the
  32   output HTML node
  33 * an ``odoo`` pygments style based on the bootstrap_ documentation's
  34 * the normal Sphinx sidebars are suppressed and a new sidebar is injected in
  35   ``div.document`` (``sidebar1`` is outside in the base Sphinx layout)
  36 * HTML5 doctype
  37
  38 Additional features
  39 -------------------
  40
  41 * versions switcher, uses the ``canonical_root`` setting and an additional
  42   ``versions`` setting which should be a comma-separated list of available
  43   versions. Appends the each version and page name to the root, and displays
  44   a list of those links on the current page
  45 * canonical urls, requires a ``canonical_root`` setting value, and optionally
  46   a ``canonical_branch`` (default: ``master``)
  47 * :guilabel:`Edit on github` link in Sphinx pages if ``github_user`` and
  48   ``github_project`` are provided
  49 * :guilabel:`[source]` links in autodoc content links to github with the same
  50   requirements (requires Sphinx 1.2)
  51 * ``aphorism`` class for admonitions, makes the first line of the admonition
  52   inline and the same size as the admonition category (mostly for short,
  53   single-phrase admonitions)
  54 * ``exercise`` directive, mostly for training-type documents, the
  55   ``solutions`` tag_ can be used to conditionally show e.g. solutions
  56 * a number of straight-to-HTML directives:
  57
  58   ``h:div``
  59     a straight div, can be used instead of ``container`` (which adds the
  60     ``container`` class to the div it generates, that's really not compatible
  61     with Bootstrap_)
  62   ``h:address``
  63     generates an ``<address>`` node
  64   a bunch of roles straight to HTML inline
  65     ``mark``, ``insert``, ``delete``, ``strikethrough``, ``small`, ``kbd`` and
  66     ``var`` generate the corresponding HTML element
  67
  68 Requirements
  69 ------------
  70
  71 * Sphinx 1.1, 1.2 for code Python code links
  72 * sphinx-patchqueue (for the content, not the theme)
  73
  74 .. _lessc: http://lesscss.org/#using-less
  75 .. _bootstrap: http://getbootstrap.com
  76 .. _sphinx: http://sphinx-doc.org
  77 .. _tag: http://sphinx-doc.org/markup/misc.html#including-content-based-on-tags