From d45acdb7268fec4a09a458e773f7d938aceca891 Mon Sep 17 00:00:00 2001
From: Pablo Piskunow <pablo.perez.piskunow@gmail.com>
Date: Thu, 22 Jun 2017 20:39:54 +0200
Subject: [PATCH] add links in the documentation to the source code
---
.gitlab-ci.yml | 2 +-
doc/source/conf.py | 32 ++++++++++++++++++++++++++++++--
2 files changed, 31 insertions(+), 3 deletions(-)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 9d0e4c4d..6972d55b 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -58,7 +58,7 @@ build documentation:
stage: test
script:
- pip3 install sympy
- - make -C doc realclean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -W'
+ - make -C doc realclean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -W' REFNAME="${CI_COMMIT_TAG:-$CI_COMMIT_SHA}" SOURCE_URL="$CI_PROJECT_URL"/blob
artifacts:
paths:
- doc/build/html/
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 265357df..1af1f28a 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -27,7 +27,7 @@ sys.path.insert(0, os.path.abspath('../sphinxext'))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary',
'sphinx.ext.todo', 'sphinx.ext.mathjax', 'numpydoc',
- 'kwantdoc']
+ 'kwantdoc', 'sphinx.ext.linkcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['../templates']
@@ -43,7 +43,7 @@ master_doc = 'index'
# General information about the project.
project = 'Kwant'
-copyright = '2011-2015, C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov, X. Waintal (CEA), and others'
+copyright = '2011-2017, C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov, X. Waintal (CEA), and others'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -231,6 +231,7 @@ autosummary_generate = True
autoclass_content = "both"
autodoc_default_flags = ['show-inheritance']
+
# -- Teach Sphinx to document bound methods like functions ---------------------
import types
from sphinx.ext import autodoc
@@ -271,3 +272,30 @@ nitpick_ignore = [('py:class', 'Warning'), ('py:class', 'Exception'),
# Use custom MathJax CDN, as cdn.mathjax.org will soon shut down
mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
+
+
+# -- Make Sphinx insert source code links --------------------------------------
+def linkcode_resolve(domain, info):
+ def find_source():
+ # try to find the file and line number, based on code from numpy:
+ # https://github.com/numpy/numpy/blob/master/doc/source/conf.py#L286
+ obj = sys.modules[info['module']]
+ for part in info['fullname'].split('.'):
+ obj = getattr(obj, part)
+ import inspect
+ fn = inspect.getsourcefile(obj)
+ fn = os.path.relpath(fn, start=os.path.dirname(kwant.__file__))
+ source, lineno = inspect.getsourcelines(obj)
+ return fn, lineno, lineno + len(source) - 1
+
+ if domain != 'py' or not info['module']:
+ return None
+ try:
+ filename = 'kwant/%s#L%d-%d' % find_source()
+ except Exception:
+ filename = info['module'].replace('.', '/') + '.py'
+ source_branch = os.environ.get('REFNAME', 'master')
+ url = os.environ.get('SOURCE_URL',
+ "https://gitlab.kwant-project.org/kwant/kwant/blob")
+
+ return "{}/{}/{}".format(url, source_branch, filename)
--
GitLab