Merge pull request #125 from dihm/sphinx_updates

Sphinx autosummary updates

Author: dihm

docs/source/_templates/autosummary-module.rst

@@ -3,7 +3,7 @@
 .. automodule:: {{ fullname }}
 
    {% block attributes %}
-   {% if attributes %}
+   {%- if attributes %}
    .. rubric:: {{ _('Module Attributes') }}
 
    .. autosummary::
@@ -12,10 +12,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block functions %}
-   {% if functions %}
+   {%- block functions %}
+   {%- if functions %}
    .. rubric:: {{ _('Functions') }}
 
    .. autosummary::
@@ -24,10 +24,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block classes %}
-   {% if classes %}
+   {%- block classes %}
+   {%- if classes %}
    .. rubric:: {{ _('Classes') }}
 
    .. autosummary::
@@ -37,10 +37,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block exceptions %}
-   {% if exceptions %}
+   {%- block exceptions %}
+   {%- if exceptions %}
    .. rubric:: {{ _('Exceptions') }}
 
    .. autosummary::
@@ -49,4 +49,18 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
+
+{%- block modules %}
+{%- if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary-module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{%- endblock %}

docs/source/api/index.rst

@@ -4,6 +4,7 @@ API Reference
 
 .. autosummary::
    :toctree: _autosummary
+   :template: autosummary-module.rst
    :recursive:
 
    lyse

docs/source/conf.py

@@ -163,20 +163,29 @@
     labscript_suite_doc_version = 'latest'
 
 # add intersphinx references for each component
+labscript_intersphinx_mapping = {}
 for ls_prog in labscript_suite_programs:
-    intersphinx_mapping[ls_prog] = (
+    val = (
         'https://docs.labscriptsuite.org/projects/{}/en/{}/'.format(
             ls_prog, labscript_suite_doc_version
         ),
         None,
     )
+    labscript_intersphinx_mapping[ls_prog] = val
+    if ls_prog != project:
+        # don't add intersphinx for current project
+        # if internal links break, they can silently be filled by links to existing online docs
+        # this is confusing and difficult to detect
+        intersphinx_mapping[ls_prog] = val
 
 # add intersphinx reference for the metapackage
 if project != "the labscript suite":
-    intersphinx_mapping['labscript-suite'] = (
+    val = (
         'https://docs.labscriptsuite.org/en/{}/'.format(labscript_suite_doc_version),
         None,
     )
+    intersphinx_mapping['labscript-suite'] = val
+    labscript_intersphinx_mapping['labscript-suite'] = val
 
 # Make `some code` equivalent to :code:`some code`
 default_role = 'code'
@@ -226,7 +235,7 @@ def setup(app):
     with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f:
         f.write(
             template.render(
-                intersphinx_mapping=intersphinx_mapping,
+                intersphinx_mapping=labscript_intersphinx_mapping,
                 programs=labscript_suite_programs,
                 current_project=project,
                 img_path=img_path