[ADD] doc's readme

* also only enable linkcode if Sphinx >= 1.2
* fix html inline roles?
Xavier Morel 2014-09-04 11:08:54 +02:00
parent 2942492245
commit 39208e1f42
4 changed files with 80 additions and 1 deletions

doc/README.rst Normal file
View File

@ -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
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:
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_)
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
* 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

View File

@ -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')

View File

@ -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):

View File

@ -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 = [
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']