[ADD] support for canonical urls in technical doc
* canonical_root setting is the path to the root of the canonical sphinx doc, if not set no canonical link is generated, must end with "/" * canonical_branch defines the canonical branch to which to redirect, defaults to master also various side-fixes: * disabled permalinks in sphinx instead of hiding them via CSS * improved generation of github links, removed _app global and setting of linkcode_resolve in conf.py
This commit is contained in:
parent
f00bf9a461
commit
958f9106dd
|
@ -3,53 +3,54 @@ import importlib
|
||||||
import os.path
|
import os.path
|
||||||
from urlparse import urlunsplit
|
from urlparse import urlunsplit
|
||||||
|
|
||||||
# FIXME: better way to handle this?
|
|
||||||
_app = None
|
|
||||||
def setup(app):
|
def setup(app):
|
||||||
global _app
|
|
||||||
_app = app
|
|
||||||
app.add_config_value('github_user', None, 'env')
|
app.add_config_value('github_user', None, 'env')
|
||||||
app.add_config_value('github_project', None, 'env')
|
app.add_config_value('github_project', None, 'env')
|
||||||
|
app.connect('html-page-context', add_doc_link)
|
||||||
|
|
||||||
def linkcode_resolve(domain, info):
|
def linkcode_resolve(domain, info):
|
||||||
# TODO: js?
|
""" Resolves provided object to corresponding github URL
|
||||||
if domain != 'py':
|
"""
|
||||||
return None
|
# TODO: js?
|
||||||
|
if domain != 'py':
|
||||||
|
return None
|
||||||
|
if not (app.config.github_user and app.config.github_project):
|
||||||
|
return None
|
||||||
|
|
||||||
module, fullname = info['module'], info['fullname']
|
module, fullname = info['module'], info['fullname']
|
||||||
# TODO: attributes/properties don't have modules, maybe try to look them
|
# TODO: attributes/properties don't have modules, maybe try to look
|
||||||
# up based on their cached host object?
|
# them up based on their cached host object?
|
||||||
if not module:
|
if not module:
|
||||||
return None
|
return None
|
||||||
|
|
||||||
obj = importlib.import_module(module)
|
obj = importlib.import_module(module)
|
||||||
for item in fullname.split('.'):
|
for item in fullname.split('.'):
|
||||||
obj = getattr(obj, item, None)
|
obj = getattr(obj, item, None)
|
||||||
|
|
||||||
if obj is None:
|
if obj is None:
|
||||||
return None
|
return None
|
||||||
|
|
||||||
# get original from decorated methods
|
# get original from decorated methods
|
||||||
try: obj = getattr(obj, '_orig')
|
try: obj = getattr(obj, '_orig')
|
||||||
except AttributeError: pass
|
except AttributeError: pass
|
||||||
|
|
||||||
try:
|
try:
|
||||||
obj_source_path = inspect.getsourcefile(obj)
|
obj_source_path = inspect.getsourcefile(obj)
|
||||||
_, line = inspect.getsourcelines(obj)
|
_, line = inspect.getsourcelines(obj)
|
||||||
except (TypeError, IOError):
|
except (TypeError, IOError):
|
||||||
# obj doesn't have a module, or something
|
# obj doesn't have a module, or something
|
||||||
return None
|
return None
|
||||||
|
|
||||||
import openerp
|
import openerp
|
||||||
project_root = os.path.join(os.path.dirname(openerp.__file__), '..')
|
project_root = os.path.join(os.path.dirname(openerp.__file__), '..')
|
||||||
return make_github_link(
|
return make_github_link(
|
||||||
os.path.relpath(obj_source_path, project_root),
|
app,
|
||||||
line)
|
os.path.relpath(obj_source_path, project_root),
|
||||||
|
line)
|
||||||
|
app.config.linkcode_resolve = linkcode_resolve
|
||||||
|
|
||||||
def make_github_link(path, line=None, mode="blob"):
|
def make_github_link(app, path, line=None, mode="blob"):
|
||||||
config = _app.config
|
config = app.config
|
||||||
if not (config.github_user and config.github_project):
|
|
||||||
return None
|
|
||||||
|
|
||||||
urlpath = "/{user}/{project}/{mode}/{branch}/{path}".format(
|
urlpath = "/{user}/{project}/{mode}/{branch}/{path}".format(
|
||||||
user=config.github_user,
|
user=config.github_user,
|
||||||
|
@ -66,6 +67,18 @@ def make_github_link(path, line=None, mode="blob"):
|
||||||
'' if line is None else 'L%d' % line
|
'' if line is None else 'L%d' % line
|
||||||
))
|
))
|
||||||
|
|
||||||
def github_doc_link(pagename, mode='blob'):
|
def add_doc_link(app, pagename, templatename, context, doctree):
|
||||||
return make_github_link(
|
""" Add github_link function linking to the current page on github """
|
||||||
'doc/%s%s' % (pagename, _app.config.source_suffix), mode=mode)
|
if not app.config.github_user and app.config.github_project:
|
||||||
|
return
|
||||||
|
|
||||||
|
def github_doc_link(mode='blob'):
|
||||||
|
""" returns the github URL for the current page
|
||||||
|
|
||||||
|
:param str mode: 'edit' for edition view
|
||||||
|
"""
|
||||||
|
return make_github_link(
|
||||||
|
app,
|
||||||
|
'doc/%s%s' % (pagename, app.config.source_suffix),
|
||||||
|
mode=mode)
|
||||||
|
context['github_link'] = github_doc_link
|
||||||
|
|
|
@ -14,6 +14,12 @@
|
||||||
<!doctype html>
|
<!doctype html>
|
||||||
{%- endblock -%}
|
{%- endblock -%}
|
||||||
|
|
||||||
|
{%- block extrahead -%}
|
||||||
|
{%- if canonical -%}
|
||||||
|
<link rel="canonical" href="{{ canonical }}"/>
|
||||||
|
{%- endif -%}
|
||||||
|
{%- endblock -%}
|
||||||
|
|
||||||
{%- block content -%}
|
{%- block content -%}
|
||||||
<div class="document-super">
|
<div class="document-super">
|
||||||
{{ super() }}
|
{{ super() }}
|
||||||
|
@ -27,11 +33,11 @@
|
||||||
<div class="sphinxsidebarwrapper">
|
<div class="sphinxsidebarwrapper">
|
||||||
{{ toctree(maxdepth=4, collapse=False, includehidden=True,
|
{{ toctree(maxdepth=4, collapse=False, includehidden=True,
|
||||||
main_navbar=False, titles_only=False) }}
|
main_navbar=False, titles_only=False) }}
|
||||||
{% if github %}
|
{% if github_link %}
|
||||||
<p><a href="{{ github(pagename) }}" class="github">
|
<p><a href="{{ github_link() }}" class="github">
|
||||||
Edit on GitHub
|
Edit on GitHub
|
||||||
</a></p>
|
</a></p>
|
||||||
{% endif %}
|
{% endif %}
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
{{ super() }}
|
{{ super() }}
|
||||||
|
|
|
@ -6540,9 +6540,6 @@ body {
|
||||||
margin-bottom: 0;
|
margin-bottom: 0;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
.headerlink {
|
|
||||||
display: none;
|
|
||||||
}
|
|
||||||
.viewcode-link {
|
.viewcode-link {
|
||||||
font-weight: normal;
|
font-weight: normal;
|
||||||
float: right;
|
float: right;
|
||||||
|
|
|
@ -348,10 +348,6 @@ body {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// hide header ¶ link
|
|
||||||
.headerlink {
|
|
||||||
display: none;
|
|
||||||
}
|
|
||||||
// move [source] link to the right
|
// move [source] link to the right
|
||||||
.viewcode-link {
|
.viewcode-link {
|
||||||
font-weight: normal;
|
font-weight: normal;
|
||||||
|
|
20
doc/conf.py
20
doc/conf.py
|
@ -119,6 +119,8 @@ html_static_path = ['_static']
|
||||||
|
|
||||||
html_style = "odoo.css"
|
html_style = "odoo.css"
|
||||||
|
|
||||||
|
html_add_permalinks = False
|
||||||
|
|
||||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||||
# using the given strftime format.
|
# using the given strftime format.
|
||||||
#html_last_updated_fmt = '%b %d, %Y'
|
#html_last_updated_fmt = '%b %d, %Y'
|
||||||
|
@ -164,10 +166,20 @@ intersphinx_mapping = {
|
||||||
'werkzeug': ('http://werkzeug.pocoo.org/docs/0.9/', None),
|
'werkzeug': ('http://werkzeug.pocoo.org/docs/0.9/', None),
|
||||||
}
|
}
|
||||||
|
|
||||||
from odoodoc.github import linkcode_resolve, github_doc_link
|
|
||||||
github_user = 'odoo'
|
github_user = 'odoo'
|
||||||
github_project = 'odoo'
|
github_project = 'odoo'
|
||||||
|
|
||||||
html_context = {
|
def setup(app):
|
||||||
'github': github_doc_link
|
app.connect('html-page-context', canonicalize)
|
||||||
}
|
app.add_config_value('canonical_root', None, 'env')
|
||||||
|
app.add_config_value('canonical_branch', 'master', 'env')
|
||||||
|
def canonicalize(app, pagename, templatename, context, doctree):
|
||||||
|
if not app.config.canonical_root:
|
||||||
|
return
|
||||||
|
|
||||||
|
context['canonical'] = "{canonical_url}{canonical_branch}/{canonical_page}".format(
|
||||||
|
canonical_url=app.config.canonical_root,
|
||||||
|
canonical_branch=app.config.canonical_branch,
|
||||||
|
canonical_page=(pagename + '.html').replace('index.html', '')
|
||||||
|
.replace('index/', ''),
|
||||||
|
)
|
||||||
|
|
Loading…
Reference in New Issue