summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rwxr-xr-xdoc/source/conf.py4
-rw-r--r--doc/source/usage.rst11
-rw-r--r--oslosphinx/__init__.py32
3 files changed, 33 insertions, 14 deletions
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8b66547..09b7191 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -26,6 +26,8 @@ extensions = [
'oslosphinx'
]
+oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/oslosphinx'
+
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable
@@ -72,4 +74,4 @@ latex_documents = [
]
# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None} \ No newline at end of file
+#intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index a291a3c..5aca6b5 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -13,3 +13,14 @@ If you are an incubating project, set::
html_theme_options = {'incubating': True}
in your conf.py as well, to enable the Incubation theme.
+
+Linking to a Source Repository
+==============================
+
+``oslosphinx`` defines a configuration option ``oslosphinx_cgit_link``
+which should be the URL to the git repository browser for the project
+being documented. The default is a guess, and will be right for a lot
+of projects, but to ensure that it is correct in all situations it is
+best to set the value in conf.py::
+
+ oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/oslosphinx'
diff --git a/oslosphinx/__init__.py b/oslosphinx/__init__.py
index c088e84..a7d3c10 100644
--- a/oslosphinx/__init__.py
+++ b/oslosphinx/__init__.py
@@ -18,22 +18,24 @@ import subprocess
CGIT_BASE = 'http://git.openstack.org/cgit/'
-_cgit_link = None
+
+
+def _guess_cgit_link():
+ try:
+ git_remote = subprocess.check_output(
+ ['git', 'config', '--local', '--get', 'remote.origin.url']
+ )
+ except subprocess.CalledProcessError:
+ return None
+ else:
+ parsed = parse.urlparse(git_remote)
+ return CGIT_BASE + parsed.path.lstrip('/')
def _html_page_context(app, pagename, templatename, context, doctree):
- global _cgit_link
- if _cgit_link is None:
- try:
- git_remote = subprocess.check_output(
- ['git', 'config', '--local', '--get', 'remote.origin.url']
- )
- except subprocess.CalledProcessError:
- _cgit_link = 'unknown'
- else:
- parsed = parse.urlparse(git_remote)
- _cgit_link = CGIT_BASE + parsed.path.lstrip('/')
- context['cgit_link'] = _cgit_link
+ # Insert the cgit link into the template context.
+ context['cgit_link'] = app.config.oslosphinx_cgit_link
+ return context
def builder_inited(app):
@@ -60,3 +62,7 @@ def builder_inited(app):
def setup(app):
app.connect('builder-inited', builder_inited)
+ # Try to guess at the default value for where the cgit repository
+ # is.
+ cgit_link = _guess_cgit_link()
+ app.add_config_value('oslosphinx_cgit_link', cgit_link, 'env')