Merge pull request #1534 from brian-team/fix_doc_reference_issues

Fix reference doc issues

brian2/sphinxext/docscrape.py

@@ -148,7 +148,7 @@ def _strip(self, doc):
                 stop = i
                 break
 
-        return doc[start:-stop]
+        return doc[start : len(doc) - stop]
 
     def _read_to_next_section(self):
         section = self._doc.read_to_next_empty_line()

brian2/sphinxext/examplefinder.py

@@ -64,8 +64,12 @@ def auto_find_examples(obj, headersymbol="="):
     make mistakes but is usually going to be correct).
     """
     name = obj.__name__
-    examples = sorted(the_examples_map[name])
-    tutorials = sorted(the_tutorials_map[name])
+    # These will only go through the examples/tutorials once. The dictionaries are cached in the
+    # module variables `the_examples_map` and `the_tutorials_map`.
+    examples_map = get_examples_map()
+    examples = sorted(examples_map[name])
+    tutorials_map = get_tutorials_map()
+    tutorials = sorted(tutorials_map[name])
     if len(examples + tutorials) == 0:
         return ""
     txt = "Tutorials and examples using this"

dev/tools/docs/build_html_brian2.py

@@ -6,7 +6,7 @@
 from sphinx.cmd.build import main as sphinx_main
 import sys
 
-os.chdir('../../../docs_sphinx')
+os.chdir(os.path.join(os.path.dirname(__file__), '../../../docs_sphinx'))
 if os.path.exists('../docs'):
     shutil.rmtree('../docs')
 # Some code (e.g. the definition of preferences) might need to know that Brian

dev/tools/docs/quick_rebuild_html_brian2.py

@@ -13,7 +13,7 @@
 # a documentation build
 os.environ['READTHEDOCS'] = 'True'
 
-os.chdir('../../../docs_sphinx')
+os.chdir(os.path.join(os.path.dirname(__file__), '../../../docs_sphinx'))
 if os.path.exists('../docs'):
     shutil.rmtree('../docs')
 sys.exit(sphinx_main(['-b', 'html', '.', '../docs']))