Browse Source

[IMP] doc: indexify index

* opt-in toc navification
* unhide index toctree, it's now back to a list of documents
* remove text thing
master
Xavier Morel 7 years ago
parent
commit
f302c123ea
  1. 5
      doc/_themes/odoodoc/layout.html
  2. 39
      doc/_themes/odoodoc/sphinx_monkeypatch.py
  3. BIN
      doc/images/view-on-github.png
  4. 28
      doc/index.rst
  5. 2
      doc/reference/cmdline.rst

5
doc/_themes/odoodoc/layout.html

@ -32,7 +32,7 @@
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
{{ toctree(maxdepth=4, collapse=False, includehidden=True,
main_navbar=False, titles_only=False) }}
navbar='side', titles_only=False) }}
{% if github_link %}
<p><a href="{{ github_link(mode='edit') }}" class="github">
Edit on GitHub
@ -72,7 +72,8 @@
{% endif %}
</div>
<nav class="collapse navbar-collapse navbar-main" role="navigation">
{{ toctree(titles_only=True, maxdepth=2, includehidden=True, collapse=False) }}
{{ toctree(titles_only=True, maxdepth=2, includehidden=True,
collapse=False, navbar='main') }}
</nav>
</div>
</header>

39
doc/_themes/odoodoc/sphinx_monkeypatch.py

@ -1,7 +1,6 @@
# -*- coding: utf-8 -*-
import sphinx.roles
import sphinx.environment
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.writers.html import HTMLTranslator
from docutils.writers.html4css1 import HTMLTranslator as DocutilsTranslator
@ -9,27 +8,17 @@ def patch():
# navify toctree (oh god)
@monkey(sphinx.environment.BuildEnvironment)
def resolve_toctree(old_resolve, self, *args, **kwargs):
""" If main_navbar, bootstrapify TOC to yield a navbar
""" If navbar, bootstrapify TOC to yield a navbar
"""
main_navbar = kwargs.pop('main_navbar', False)
navbar = kwargs.pop('navbar', None)
toc = old_resolve(self, *args, **kwargs)
if toc is None:
return None
navbarify(toc[0], main_navbar=main_navbar)
navbarify(toc[0], navbar=navbar)
return toc
@monkey(StandaloneHTMLBuilder)
def _get_local_toctree(old_local, self, *args, **kwargs):
""" _get_local_toctree generates a documentation toctree for the local
document (?), called from handle_page
"""
# so can call toctree(main_navbar=False)
d = {'main_navbar': True}
d.update(kwargs)
return old_local(self, *args, **d)
# monkeypatch visit_table to remove border and add .table
HTMLTranslator.visit_table = visit_table
# disable colspec crap
@ -37,11 +26,18 @@ def patch():
# copy data- attributes straight from source to dest
HTMLTranslator.starttag = starttag_data
def navbarify(node, main_navbar=False):
# add classes to toplevel
if not main_navbar:
navify([node])
else:
def navbarify(node, navbar=None):
"""
:param node: toctree node to navbarify
:param navbar: Whether this toctree is a 'main' navbar, a 'side' navbar or
not a navbar at all
"""
if navbar == 'side':
for n in node.traverse():
if n.tagname == 'bullet_list':
n['classes'].append('nav')
elif navbar == 'main':
# add classes to just toplevel
node['classes'].extend(['nav', 'navbar-nav', 'navbar-right'])
for list_item in node.children:
# bullet_list
@ -59,11 +55,6 @@ def navbarify(node, main_navbar=False):
link.attributes['data-toggle'] = 'dropdown'
# list_item.bullet_list
list_item.children[1]['classes'].append('dropdown-menu')
def navify(nodes):
for node in nodes:
if node.tagname == 'bullet_list':
node['classes'].append('nav')
navify(node.children)
def visit_table(self, node):
"""

BIN
doc/images/view-on-github.png

Before

Width: 219  |  Height: 108  |  Size: 1.5 KiB

28
doc/index.rst

@ -4,34 +4,12 @@ odoo developer documentation
Welcome to the Odoo developer documentation.
This documentation is incomplete and may contain errors, if you wish to
contribute, every page should have a :guilabel:`View on Github` link:
.. image:: images/view-on-github.*
:align: center
Through this link you can edit documents and submit changes for review using
`github's web interface
<https://help.github.com/articles/editing-files-in-your-repository/>`_.
Contributions are welcome and appreciated.
.. todo:: what's the documentation's license?
The documentation is currently organized in four sections:
* :doc:`tutorials`, aimed at introducing the primary areas of developing Odoo
modules
* :doc:`reference`, which ought be the complete and canonical documentation
for Odoo subsystems
* :doc:`modules`, documenting useful specialized modules and integration
methods (and currently empty)
.. hidden toctree w/o titlesonly otherwise the titlesonly "sticks" to
in-document toctrees and we can't have a toctree showing both "sibling"
pages and current document sections
.. titlesonly breaks level 3 (~in-document) toc of left navbar, so use
maxdepth instead
.. toctree::
:hidden:
:maxdepth: 2
tutorials
reference

2
doc/reference/cmdline.rst

@ -71,7 +71,7 @@ Scaffolding is available via the :command:`odoo.py scaffold` subcommand.
.. option:: -t <template>
a template directory, files are passed through jinja2_ then copied to
the :option:`destination` directory
the ``destination`` directory
.. option:: name

Loading…
Cancel
Save