From 39208e1f42e058175995e07279d1a13a9377e484 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Thu, 4 Sep 2014 11:08:54 +0200
Subject: [PATCH] [ADD] doc's readme

* also only enable linkcode if Sphinx >= 1.2
* fix html inline roles?
---
 doc/README.rst                     | 73 ++++++++++++++++++++++++++++++
 doc/_themes/odoodoc/github.py      |  1 +
 doc/_themes/odoodoc/html_domain.py |  1 +
 doc/conf.py                        |  6 ++-
 4 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 doc/README.rst

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644
index 00000000000..b9b6d63f45a
--- /dev/null
+++ b/doc/README.rst
@@ -0,0 +1,73 @@
+.. orphan:: true
+
+==================
+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
+-------------------
+
+* 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
diff --git a/doc/_themes/odoodoc/github.py b/doc/_themes/odoodoc/github.py
index 0591a4203cc..ec6bba3c866 100644
--- a/doc/_themes/odoodoc/github.py
+++ b/doc/_themes/odoodoc/github.py
@@ -2,6 +2,7 @@ import inspect
 import importlib
 import os.path
 from urlparse import urlunsplit
+import sphinx
 
 def setup(app):
     app.add_config_value('github_user', None, 'env')
diff --git a/doc/_themes/odoodoc/html_domain.py b/doc/_themes/odoodoc/html_domain.py
index 88fd239b05d..07c6c07fc9a 100644
--- a/doc/_themes/odoodoc/html_domain.py
+++ b/doc/_themes/odoodoc/html_domain.py
@@ -4,6 +4,7 @@ from docutils import nodes, utils
 from docutils.parsers.rst import Directive, directives, docutils
 from docutils.parsers.rst.directives.body import LineBlock
 
+import sphinx.roles
 from sphinx.domains import Domain
 
 def setup(app):
diff --git a/doc/conf.py b/doc/conf.py
index 005aefdb51c..a55a48c0a96 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import sys, os
+import sphinx
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -22,10 +23,13 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.linkcode',
     'odoodoc',
     'patchqueue'
 ]
+if sphinx.__version__.split('.') >= ['1', '2']:
+    # linkcode is only available from Sphinx 1.2
+    extensions.insert(0, 'sphinx.ext.linkcode')
+
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']