Merge pull request #118 from dihm/rtd_fixes

Sphinx autosummary fixes

Author: dihm

docs/source/_templates/autosummary-module.rst

@@ -1,23 +1,9 @@
 {{ fullname | escape | underline}}
 
-{% block submodules %}
-{% if modules %}
-.. rubric:: {{ _('Sub-Modules') }}
-.. autosummary::
-   :toctree: 
-   :template: autosummary-module.rst
-   :recursive:
-
-   {% for item in modules %}
-   {{ item }}
-   {%- endfor %}
-{% endif %}
-{% endblock %}
-
 .. automodule:: {{ fullname }}
 
    {% block attributes %}
-   {% if attributes %}
+   {%- if attributes %}
    .. rubric:: {{ _('Module Attributes') }}
 
    .. autosummary::
@@ -26,10 +12,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block functions %}
-   {% if functions %}
+   {%- block functions %}
+   {%- if functions %}
    .. rubric:: {{ _('Functions') }}
 
    .. autosummary::
@@ -38,10 +24,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block classes %}
-   {% if classes %}
+   {%- block classes %}
+   {%- if classes %}
    .. rubric:: {{ _('Classes') }}
 
    .. autosummary::
@@ -51,10 +37,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block exceptions %}
-   {% if exceptions %}
+   {%- block exceptions %}
+   {%- if exceptions %}
    .. rubric:: {{ _('Exceptions') }}
 
    .. autosummary::
@@ -63,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:
 
    labscript_utils

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

docs/source/labconfig.rst

@@ -7,7 +7,9 @@ The name of this file must be the host computer's system name.
 So if my system's name was `heisenberg`, the labconfig file name would be `heisenberg.ini`.
 This file should be located in the `labscript-suite` directory in the user space, in the `labconfig` subdirectory.
 
-When :doc:`installing the **labscript-suite** for the first time <labscript-suite:installation/index>`, running the `labscript-profile-create` command will automatically generate the `labscript-suite` user space directory in the correct place and generate a `labconfig.ini` file for use on your system.
+When :doc:`installing the **labscript-suite** for the first time <labscript-suite:installation/index>`,
+running the `labscript-profile-create` command will automatically generate the `labscript-suite` user space directory in the correct place
+and generate a `labconfig.ini` file for use on your system.
 By editing the `ini` file named after your system, you can update the configuration settings of your **labscript-suite** installation.
 
 The Default *labconfig.ini*