Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ instance/

# Sphinx documentation
docs/_build/
docs/source/api/_autosummary/

# PyBuilder
.pybuilder/
Expand Down
32 changes: 32 additions & 0 deletions docs/source/_templates/autosummary-class.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
:members:
:undoc-members:
:show-inheritance:

{% block methods %}
.. automethod:: __init__

{% if methods %}
.. rubric:: {{ _('Methods') }}

.. autosummary::
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Attributes') }}

.. autosummary::
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
66 changes: 66 additions & 0 deletions docs/source/_templates/autosummary-module.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}

{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Module Attributes') }}

.. autosummary::
:toctree:
{% for item in attributes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block functions %}
{% if functions %}
.. rubric:: {{ _('Functions') }}

.. autosummary::
:toctree:
{% for item in functions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block classes %}
{% if classes %}
.. rubric:: {{ _('Classes') }}

.. autosummary::
:toctree:
:template: autosummary-class.rst
{% for item in classes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block exceptions %}
{% if exceptions %}
.. rubric:: {{ _('Exceptions') }}

.. autosummary::
:toctree:
{% for item in exceptions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
:toctree:
:template: autosummary-module.rst
:recursive:
{% for item in modules %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
9 changes: 0 additions & 9 deletions docs/source/api/clockline.rst

This file was deleted.

9 changes: 0 additions & 9 deletions docs/source/api/device.rst

This file was deleted.

15 changes: 6 additions & 9 deletions docs/source/api/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,10 @@
API Reference
=============

.. toctree::
:maxdepth: 2

device
pseudoclockdevice
pseudoclock
clockline
intermediatedevice

.. autosummary::
:toctree: _autosummary
:template: autosummary-module.rst
:recursive:

labscript.labscript
labscript.functions
9 changes: 0 additions & 9 deletions docs/source/api/intermediatedevice.rst

This file was deleted.

9 changes: 0 additions & 9 deletions docs/source/api/pseudoclock.rst

This file was deleted.

9 changes: 0 additions & 9 deletions docs/source/api/pseudoclockdevice.rst

This file was deleted.

42 changes: 42 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
# ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.autosectionlabel",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
Expand All @@ -48,6 +49,8 @@
]

autodoc_typehints = 'description'
autosummary_generate = True
add_module_names = False

# Prefix each autosectionlabel with the name of the document it is in and a colon
autosectionlabel_prefix_document = True
Expand Down Expand Up @@ -222,3 +225,42 @@ def setup(app):
img_path=img_path
)
)

app.connect('autodoc-process-docstring', doc_coverage)
app.connect('build-finished', doc_report)


members_to_watch = ['module', 'class', 'function', 'exception', 'method', 'attribute']
doc_count = 0
undoc_count = 0
undoc_objects = []
undoc_print_objects = False


def doc_coverage(app, what, name, obj, options, lines):
global doc_count
global undoc_count
global undoc_objects

if (what in members_to_watch and len(lines) == 0):
# blank docstring detected
undoc_count += 1
undoc_objects.append(name)
else:
doc_count += 1


def doc_report(app, exception):
global doc_count
global undoc_count
global undoc_objects
# print out report of documentation coverage
total_docs = undoc_count + doc_count
if total_docs != 0:
print(f'\nAPI Doc coverage of {doc_count/total_docs:.1%}')
if undoc_print_objects or os.environ.get('READTHEDOCS'):
print('\nItems lacking documentation')
print('===========================')
print(*undoc_objects, sep='\n')
else:
print('No docs counted, run \'make clean\' then rebuild to get the count.')
3 changes: 2 additions & 1 deletion docs/source/connection_table.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ Connection Table
================
The connection table maps out the way input/output devices are connected to each other in your lab, and the channels (individual inputs/outputs) they have. The devices in your lab should be connected in a similar way to that shown in the figure below.

TODO: insert figure!
.. image:: img/connection_diagram.png
:alt: Example wiring diagram.

Here we see two :py:class:`PseudoclockDevice <labscript.PseudoclockDevice>` instances in the top tier of the diagram. They do not have a parent device that tells them when to update their output (this is true for all :py:class:`PseudoclockDevice <labscript.PseudoclockDevice>` instances). However, all but one (the master pseudoclock device) must be triggered by an output clocked by the master pseudoclock device.

Expand Down
Binary file added docs/source/img/connection_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/pyqt5-modified-objects.inv
Binary file not shown.
Loading