diff options
| -rwxr-xr-x | doc/source/conf.py | 4 | ||||
| -rw-r--r-- | doc/source/usage.rst | 11 | ||||
| -rw-r--r-- | oslosphinx/__init__.py | 32 |
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') |