diff --git a/docs/source/_templates/autosummary-module.rst b/docs/source/_templates/autosummary-module.rst index 2ce2afd..abf66c9 100644 --- a/docs/source/_templates/autosummary-module.rst +++ b/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 %} \ No newline at end of file diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index bafafcb..59bde58 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -4,6 +4,7 @@ API Reference .. autosummary:: :toctree: _autosummary + :template: autosummary-module.rst :recursive: labscript_utils diff --git a/docs/source/conf.py b/docs/source/conf.py index ed631fa..08a98bd 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/labconfig.rst b/docs/source/labconfig.rst index 9ca2399..fa72764 100644 --- a/docs/source/labconfig.rst +++ b/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 `, 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 `, +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*