-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* also only enable linkcode if Sphinx >= 1.2 * fix html inline roles?
- Loading branch information
Showing
4 changed files
with
80 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters