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 ``
``) 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 ``
`` 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']