Merge pull request #122 from dihm/rtd_fixes

Sphinx autosummary fixes

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:
 
     runmanager

docs/source/conf.py

@@ -194,20 +194,29 @@ def set_process_name(self,*args,**kwargs):
     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'
@@ -257,7 +266,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/usage.rst

@@ -48,7 +48,7 @@ located in a always visible toolbar at the top of the runmanager interface. Thes
     into hardware instructions (see :doc:`labscript <labscript:index>`).
 #.  The shot output folder: The location to store the hdf5 shot files. By default, the
     location in specified by the combination of a value in the laboratory PC configuration
-    file (see :doc:`labconfig <labscript-suite:labconfig>`), the name of the experiment logic Python file and
+    file (see :doc:`labconfig <labscript-utils:labconfig>`), the name of the experiment logic Python file and
     the current date. The location automatically updates, at midnight, to a new folder
     for the day provided the folder location is left as the default.
 #.  The BLACS hostname: The network hostname of the PC the hdf5 shot files are to

runmanager/__init__.py

@@ -825,8 +825,8 @@ def compile_labscript_async(labscript_file, run_file,
     done_callback will be called with a boolean argument indicating success. Note that
     the zmq communication will be encrypted, or not, according to security settings in
     labconfig. If you want to receive the data on a zmq socket, do so using a PULL
-    socket created from a labscript_utils.ls_zprocess.Context, or using a
-    labscript_utils.ls_zprocess.ZMQServer. These subclasses will also be configured
+    socket created from a :class:`labscript_utils.ls_zprocess.Context`, or using a
+    :class:`labscript_utils.ls_zprocess.ZMQServer`. These subclasses will also be configured
     with the appropriate security settings and will be able to receive the messages.
 
     Args:
@@ -867,8 +867,8 @@ def compile_multishot_async(labscript_file, run_files,
     stream_port via zmq push as it spews forth, and when each compilation is complete,
     done_callback will be called with a boolean argument indicating success. Compilation
     will stop after the first failure.  If you want to receive the data on a zmq socket,
-    do so using a PULL socket created from a labscript_utils.ls_zprocess.Context, or
-    using a labscript_utils.ls_zprocess.ZMQServer. These subclasses will also be
+    do so using a PULL socket created from a :class:`labscript_utils.ls_zprocess.Context`, or
+    using a :class:`labscript_utils.ls_zprocess.ZMQServer`. These subclasses will also be
     configured with the appropriate security settings and will be able to receive the
     messages.
     
@@ -913,12 +913,12 @@ def compile_labscript_with_globals_files_async(labscript_file, globals_files, ou
     """Compiles labscript_file with multiple globals files into a directory.
     
     Instead, stderr and stdout will be put to
-    stream_port via zmq push in the multipart message format ['stdout','hello, world\n']
+    stream_port via zmq push in the multipart message format `['stdout','hello, world\\n']`
     etc. When compilation is finished, the function done_callback will be called a
     boolean argument indicating success or failure.  If you want to receive the data on
     a zmq socket, do so using a PULL socket created from a
-    labscript_utils.ls_zprocess.Context, or using a
-    labscript_utils.ls_zprocess.ZMQServer. These subclasses will also be configured with
+    :external:class:`labscript_utils.ls_zprocess.Context`, or using a
+    :external:class:`labscript_utils.ls_zprocess.ZMQServer`. These subclasses will also be configured with
     the appropriate security settings and will be able to receive the messages.
     
     Args: