Doc build fixes

brian2tools/__init__.py

@@ -1,8 +1,31 @@
 '''
 Tools for use with the Brian 2 simulator.
 '''
+import logging
+
 from .baseexport import *
 from .mdexport import *
 from .nmlexport import *
 from .plotting import *
 from .tests import run as test
+
+try:
+    from ._version import __version__, __version_tuple__
+except ImportError:
+    try:
+        from setuptools_scm import get_version
+
+        __version__ = get_version(
+            root="..",
+            relative_to=__file__,
+            version_scheme="post-release",
+            local_scheme="no-local-version",
+        )
+        __version_tuple__ = tuple(int(x) for x in __version__.split(".")[:3])
+    except ImportError:
+        logging.getLogger(__name__).warning(
+            "Cannot determine Brian2tools version, running from source and "
+            "setuptools_scm is not installed."
+        )
+        __version__ = "unknown"
+        __version_tuple__ = (0, 0, 0)

docs_sphinx/conf.py

@@ -12,9 +12,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
 import shlex
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -64,7 +64,7 @@
 
 # We mock modules that are not needed just for building the documentation
 import sys
-from unittest.mock import Mock, MagicMock
+from unittest.mock import MagicMock, Mock
 
 MOCK_MODULES = ['matplotlib', 'matplotlib.colors', 'matplotlib.patches', 'matplotlib.pyplot', 'matplotlib.ticker', 'matplotlib.cm',
                 'mpl_toolkits', 'mpl_toolkits.axes_grid1',
@@ -94,20 +94,15 @@
 # built documents.
 #
 import brian2tools
+
 version = brian2tools.__version__
-if version is None:
-    try:
-        from setuptools_scm import get_version
-        version = get_version(relative_to=brian2tools_dir)
-    except (ImportError, LookupError):
-        version = 'unknown'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -189,7 +184,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -414,7 +409,7 @@
                        'mayavi': ('http://docs.enthought.com/mayavi/mayavi/', None)}
 
 # Configure linking to github
-extlinks = {'issue': ('https://github.com/brian-team/brian2tools/issues/%s','#')}
+extlinks = {'issue': ('https://github.com/brian-team/brian2tools/issues/%s','# %s')}
 
 # Create api docs
 def run_apidoc(_):
@@ -425,9 +420,17 @@ def run_apidoc(_):
     brian2tools_dir = os.path.abspath(os.path.join(os.path.dirname(__file__),
                                                    '..', 'brian2tools'))
     docs_sphinx_dir = os.path.abspath(os.path.join(os.path.dirname(__file__)))
-    apidoc.main(argv=['-f', '-e', '-M',
-                      '-o', os.path.join(docs_sphinx_dir, 'reference'),
-                      brian2tools_dir, os.path.join(brian2tools_dir, 'tests')])
+    apidoc.main(
+        [
+            "-f",
+            "-e",
+            "-M",
+            "-o",
+            os.path.join(docs_sphinx_dir, "reference"),
+            brian2tools_dir,
+            os.path.join(brian2tools_dir, "tests"),
+        ]
+    )
 
 def setup(app):
     app.connect('builder-inited', run_apidoc)

docs_sphinx/release_notes.rst

@@ -10,7 +10,7 @@ This release adds a number of major new features to the package. In particular:
   biophysical properties. This feature has been developed by Kapil Kumar
   (`@kapilkd13 <https://github.com/kapilkd13>`_) as part of the
   `Google Summer of Code <https://summerofcode.withgoogle.com/>`_ 2018.
-* improved support for :doc:`exporting neuronal models to NeuroML <user/nmlexporter>,
+* improved support for :doc:`exporting neuronal models to NeuroML <user/nmlexporter>`,
   and a new :doc:`general framework to export model descriptions <user/baseexporter>`.
   As a demonstration of this framework, it is now possible to export a Brian model
   description as :doc:`human-readable markdown <user/mdexporter>`. This feature has

docs_sphinx/user/nmlimport.rst

@@ -189,7 +189,7 @@ about the cell:
     A dictionary with general properties such as the threshold condition or the
     intracellular resistivity. The names are chosen to be consistent with the argument
     names in `.~SpatialNeuron`, in many cases you should therefore be able to directly
-    pass this dictionary: ``neuron = SpatialNeuron(..., **nml_object.properties)`
+    pass this dictionary: ``neuron = SpatialNeuron(..., **nml_object.properties)``
 ``channel_properties``:
     A dictionary of reversal potentials and conductance densities for the different
     channels in the cell. The dictionary maps the name of segment groups to the name