Merge pull request #2 from emdupre/docs

[DOC] Add linkcode sphinxext

docs/conf.py

@@ -19,8 +19,11 @@
 #
 import os
 import sys
+sys.path.insert(0, os.path.abspath('sphinxext'))
 sys.path.insert(0, os.path.abspath('../tedana'))
 
+from sphinxext import make_linkcode_resolve
+
 
 # -- General configuration ------------------------------------------------
 
@@ -40,7 +43,7 @@
               'sphinx.ext.todo',
               'numpydoc',
               'sphinx.ext.ifconfig',
-              'sphinx.ext.viewcode']
+              'sphinx.ext.linkcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -188,6 +191,13 @@
 # generate autosummary even if no references
 autosummary_generate = True
 autodoc_default_flags = ['members', 'inherited-members']
+add_module_names = False
+
+# The following is used by sphinx.ext.linkcode to provide links to github
+linkcode_resolve = make_linkcode_resolve('tedana',
+                                         u'https://github.com/me-ica/'
+                                         'tedana/blob/{revision}/'
+                                         '{package}/{path}#L{lineno}')
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {

docs/sphinxext/__init__.py

@@ -0,0 +1,11 @@
+# emacs: -*- mode: python-mode; py-indent-offset: 4; tab-width: 4; indent-tabs-mode: nil -*-
+# ex: set sts=4 ts=4 sw=4 et:
+
+from .github_link import (
+    make_linkcode_resolve,
+)
+
+
+__all__ = [
+    'make_linkcode_resolve',
+    ]

docs/sphinxext/github_link.py

@@ -0,0 +1,84 @@
+from operator import attrgetter
+import inspect
+import subprocess
+import os
+import sys
+from functools import partial
+
+REVISION_CMD = 'git rev-parse --short HEAD'
+
+
+def _get_git_revision():
+    try:
+        revision = subprocess.check_output(REVISION_CMD.split()).strip()
+    except (subprocess.CalledProcessError, OSError):
+        print('Failed to execute git to get revision')
+        return None
+    return revision.decode('utf-8')
+
+
+def _linkcode_resolve(domain, info, package, url_fmt, revision):
+    """Determine a link to online source for a class/method/function
+
+    This is called by sphinx.ext.linkcode
+
+    An example with a long-untouched module that everyone has
+    >>> _linkcode_resolve('py', {'module': 'tty',
+    ...                          'fullname': 'setraw'},
+    ...                   package='tty',
+    ...                   url_fmt='http://hg.python.org/cpython/file/'
+    ...                           '{revision}/Lib/{package}/{path}#L{lineno}',
+    ...                   revision='xxxx')
+    'http://hg.python.org/cpython/file/xxxx/Lib/tty/tty.py#L18'
+    """
+
+    if revision is None:
+        return
+    if domain not in ('py', 'pyx'):
+        return
+    if not info.get('module') or not info.get('fullname'):
+        return
+
+    class_name = info['fullname'].split('.')[0]
+    if type(class_name) != str:
+        # Python 2 only
+        class_name = class_name.encode('utf-8')
+    module = __import__(info['module'], fromlist=[class_name])
+    obj = attrgetter(info['fullname'])(module)
+
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:
+        fn = None
+    if not fn:
+        try:
+            fn = inspect.getsourcefile(sys.modules[obj.__module__])
+        except Exception:
+            fn = None
+    if not fn:
+        return
+
+    fn = os.path.relpath(fn,
+                         start=os.path.dirname(__import__(package).__file__))
+    try:
+        lineno = inspect.getsourcelines(obj)[1]
+    except Exception:
+        lineno = ''
+    return url_fmt.format(revision=revision, package=package,
+                          path=fn, lineno=lineno)
+
+
+def make_linkcode_resolve(package, url_fmt):
+    """Returns a linkcode_resolve function for the given URL format
+
+    revision is a git commit reference (hash or name)
+
+    package is the name of the root module of the package
+
+    url_fmt is along the lines of ('https://github.com/USER/PROJECT/'
+                                   'blob/{revision}/{package}/'
+                                   '{path}#L{lineno}')
+    """
+    revision = _get_git_revision()
+    return partial(_linkcode_resolve, revision=revision, package=package,
+                   url_fmt=url_fmt)

tedana/tests/test_tedana.py

@@ -6,7 +6,7 @@
 import numpy as np
 import nibabel as nb
 from pathlib import Path
-from tedana.cli import run
+from tedana.cli import run_tedana
 from tedana import workflows
 
 
@@ -16,7 +16,7 @@ def test_basic_tedana():
     files.
     """
 
-    parser = run.get_parser()
+    parser = run_tedana.get_parser()
     options = parser.parse_args(['-d', '/home/neuro/data/zcat_ffd.nii.gz',
                                  '-e', '14.5', '38.5', '62.5'])
     workflows.tedana.main(**vars(options))