Skip to content

Commit f42dd4c

Browse files
dihmdihm
committed
Squashed commit of the following:
commit f6409e0 Author: David Meyer <[email protected]> Date: Tue Dec 7 10:11:56 2021 -0500 Update setup.cfg to show python 3.9 support. commit 4d26344 Merge: 62455b5 deca5d8 Author: David Meyer <[email protected]> Date: Wed Nov 10 18:42:45 2021 -0500 Merge pull request #77 from zakv/square-wave Added AnalogQuantity.square_wave(). commit deca5d8 Author: Zak V <[email protected]> Date: Wed Nov 10 18:00:24 2021 -0500 Changed the parameterization of AnalogQuantity.square_wave() inputs, then added square_wave_levels() method which uses the old parameterization. This PR also inverts the previous meaning of duty cycle in the old parameterization. Now duty cycle is the fraction of the time spent outputing `level_0` rather than `level_1` in square_wave_levels(). commit 62455b5 Merge: 13239cc bda942a Author: David Meyer <[email protected]> Date: Wed Nov 10 08:53:04 2021 -0500 Merge pull request #84 from chrisjbillington/full-unitconversion-import-path Save the full import path of unit conversion classes commit bda942a Author: chrisjbillington <[email protected]> Date: Tue Nov 9 16:50:14 2021 +1100 Save the full import path of unit conversion classes This allows unit conversion classes located outside of `labscript_utils` to be used. Closes #71 commit 13239cc Merge: 83e10e5 4716ceb Author: zakv <[email protected]> Date: Fri Aug 20 16:48:15 2021 -0400 Merge pull request #72 from zakv/save-git-info Save git info commit 83e10e5 Merge: 9fbd24c ea17d77 Author: zakv <[email protected]> Date: Fri Aug 20 16:47:49 2021 -0400 Merge pull request #73 from philipstarkey/feature/performance-improvements Performance improvements commit 9fbd24c Merge: 04db899 736cb32 Author: zakv <[email protected]> Date: Fri Aug 20 08:33:57 2021 -0400 Merge pull request #79 from zakv/fix-78 Fix #78: labscript.py accidentally overwrites dedent() commit 04db899 Merge: a805b69 9915e50 Author: David Meyer <[email protected]> Date: Fri Jul 16 14:54:58 2021 -0400 Merge pull request #74 from dihm/labscript-docs Initial pass at API docs for labscript commit 9915e50 Author: David Meyer <[email protected]> Date: Thu Jul 15 10:17:58 2021 -0400 Even more docstring coverage in the API. commit a4057e5 Author: David Meyer <[email protected]> Date: Wed Jul 14 10:38:13 2021 -0400 Adding more docstrings to the API. commit 846377d Author: David Meyer <[email protected]> Date: Wed Jul 14 10:34:02 2021 -0400 Remove colorama stuff. Doesn't work on RTD anyway. Now everything will be more consistent. commit 073ceb4 Author: David Meyer <[email protected]> Date: Wed Jul 14 10:08:19 2021 -0400 Add missing dependency that sphinx should bring in automatically but doesn't on RTD. commit 08071b1 Author: David Meyer <[email protected]> Date: Wed Jul 14 09:51:36 2021 -0400 Update sphinx pin to newest stable version. commit 4b6f805 Author: David Meyer <[email protected]> Date: Wed Jul 14 09:41:26 2021 -0400 Quick hack to get a coverage percentage of the API documentation. We can't easily use the coverage extension because it counts things documented via the `undoc-members` flag as documented! Actual items that need documenting can also be printed if desired by setting the `undoc_print_objects` flag in conf.py. This is automatically done for RTD builds. commit 09091e3 Author: David Meyer <[email protected]> Date: Tue Jul 13 18:02:21 2021 -0400 Add docstrings for all of the defined functions. commit c1960c0 Author: David Meyer <[email protected]> Date: Fri Jul 9 11:45:36 2021 -0400 Clean up warning messages and dead code. commit b9be2c3 Author: David Meyer <[email protected]> Date: Fri Jul 9 11:23:00 2021 -0400 Version bump RTD theme. commit 7e086b6 Author: David Meyer <[email protected]> Date: Fri Apr 2 13:23:33 2021 -0400 Version bump sphinx build requirement to 3.2.1 commit 689bc40 Author: David Meyer <[email protected]> Date: Fri Apr 2 12:19:55 2021 -0400 Adding the connection diagram figure from Phil's thesis. commit f5b8eed Author: David Meyer <[email protected]> Date: Tue Nov 17 07:29:34 2020 -0500 Version bump sphinx to 3.1.2 This fixes issue where autodoc does not correctly handle decorated function signatures. commit 6512ac6 Author: David Meyer <[email protected]> Date: Mon Nov 16 20:17:19 2020 -0500 Version bump sphinx Fixes issue with using autosummary templates commit 0e91b09 Author: David Meyer <[email protected]> Date: Mon Nov 16 18:39:30 2020 -0500 Initial pass at API docs for labscript. This relies on recursive features and custom templates for autosummary, as described in https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough/62613202#62613202 commit 736cb32 Author: Zak V <[email protected]> Date: Thu Feb 25 19:23:29 2021 -0500 Fixed issue 78 in which labscript.py accidentally overwrote labscript_utils.dedent() with matplotlib.cbook.dedent(). commit 054e281 Author: Zak V <[email protected]> Date: Thu Feb 25 18:40:41 2021 -0500 Added AnalogQuantity.square_wave(). commit 4716ceb Author: Zak V <[email protected]> Date: Thu Oct 15 05:47:31 2020 -0400 Reduced _vcs_cache_rlock contention in save_labscripts(). commit ea17d77 Author: Phil Starkey <[email protected]> Date: Thu Oct 15 18:50:45 2020 +1100 Performance improvements These small changes seem to improve compilation time significantly. Tests (done with saving of hg info disabled) indicate compilation time for a complex experiment is decreased somewhere between 25-33%. commit 903cc43 Author: Zak V <[email protected]> Date: Wed Oct 14 03:59:16 2020 -0400 Worked on some thread safety issues with vcs caching. commit 0f3f187 Author: Zak V <[email protected]> Date: Tue Oct 13 02:01:49 2020 -0400 Results from git/hg are now cached for faster shot compilation. commit 6022d97 Author: Zak V <[email protected]> Date: Sun Oct 4 12:52:10 2020 -0400 Added '--tags' to call to git describe. commit 2025755 Author: Zak V <[email protected]> Date: Sun Oct 4 12:38:10 2020 -0400 Updated git/hg error message. commit dc8d917 Author: Zak V <[email protected]> Date: Sun Oct 4 12:35:39 2020 -0400 Added "git describe --always HEAD" to git commands. commit 9a20221 Author: Zak V <[email protected]> Date: Sun Oct 4 12:30:44 2020 -0400 Removed "--verify" from git rev-parse call. commit 58ed6db Author: Zak V <[email protected]> Date: Sun Oct 4 12:28:35 2020 -0400 save_labscripts()'s calls to git/hg for a given file now run in parallel. commit df4e17f Author: Zak V <[email protected]> Date: Sat Oct 3 14:35:59 2020 -0400 Added support for save_hg_info and save_git_info options in the labconfig [labscript] section. commit e0073ea Author: Zak V <[email protected]> Date: Sat Oct 3 13:48:15 2020 -0400 Added support for saving git repo info.
1 parent a805b69 commit f42dd4c

16 files changed

Lines changed: 1663 additions & 258 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ instance/
7777

7878
# Sphinx documentation
7979
docs/_build/
80+
docs/source/api/_autosummary/
8081

8182
# PyBuilder
8283
.pybuilder/

‎docs/source/_templates/autosummary-class.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
:members:
7+
:undoc-members:
8+
:show-inheritance:
9+
10+
{% block methods %}
11+
.. automethod:: __init__
12+
13+
{% if methods %}
14+
.. rubric:: {{ _('Methods') }}
15+
16+
.. autosummary::
17+
{% for item in methods %}
18+
~{{ name }}.{{ item }}
19+
{%- endfor %}
20+
{% endif %}
21+
{% endblock %}
22+
23+
{% block attributes %}
24+
{% if attributes %}
25+
.. rubric:: {{ _('Attributes') }}
26+
27+
.. autosummary::
28+
{% for item in attributes %}
29+
~{{ name }}.{{ item }}
30+
{%- endfor %}
31+
{% endif %}
32+
{% endblock %}

‎docs/source/_templates/autosummary-module.rst‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. automodule:: {{ fullname }}
4+
5+
{% block attributes %}
6+
{% if attributes %}
7+
.. rubric:: {{ _('Module Attributes') }}
8+
9+
.. autosummary::
10+
:toctree:
11+
{% for item in attributes %}
12+
{{ item }}
13+
{%- endfor %}
14+
{% endif %}
15+
{% endblock %}
16+
17+
{% block functions %}
18+
{% if functions %}
19+
.. rubric:: {{ _('Functions') }}
20+
21+
.. autosummary::
22+
:toctree:
23+
{% for item in functions %}
24+
{{ item }}
25+
{%- endfor %}
26+
{% endif %}
27+
{% endblock %}
28+
29+
{% block classes %}
30+
{% if classes %}
31+
.. rubric:: {{ _('Classes') }}
32+
33+
.. autosummary::
34+
:toctree:
35+
:template: autosummary-class.rst
36+
{% for item in classes %}
37+
{{ item }}
38+
{%- endfor %}
39+
{% endif %}
40+
{% endblock %}
41+
42+
{% block exceptions %}
43+
{% if exceptions %}
44+
.. rubric:: {{ _('Exceptions') }}
45+
46+
.. autosummary::
47+
:toctree:
48+
{% for item in exceptions %}
49+
{{ item }}
50+
{%- endfor %}
51+
{% endif %}
52+
{% endblock %}
53+
54+
{% block modules %}
55+
{% if modules %}
56+
.. rubric:: Modules
57+
58+
.. autosummary::
59+
:toctree:
60+
:template: autosummary-module.rst
61+
:recursive:
62+
{% for item in modules %}
63+
{{ item }}
64+
{%- endfor %}
65+
{% endif %}
66+
{% endblock %}

‎docs/source/api/clockline.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/source/api/device.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/source/api/index.rst‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,10 @@
22
API Reference
33
=============
44

5-
.. toctree::
6-
:maxdepth: 2
7-
8-
device
9-
pseudoclockdevice
10-
pseudoclock
11-
clockline
12-
intermediatedevice
13-
5+
.. autosummary::
6+
:toctree: _autosummary
7+
:template: autosummary-module.rst
8+
:recursive:
149

10+
labscript.labscript
11+
labscript.functions

‎docs/source/api/intermediatedevice.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/source/api/pseudoclock.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/source/api/pseudoclockdevice.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/source/conf.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
# ones.
3939
extensions = [
4040
"sphinx.ext.autodoc",
41+
"sphinx.ext.autosummary",
4142
"sphinx.ext.autosectionlabel",
4243
"sphinx.ext.intersphinx",
4344
"sphinx.ext.napoleon",
@@ -48,6 +49,8 @@
4849
]
4950

5051
autodoc_typehints = 'description'
52+
autosummary_generate = True
53+
add_module_names = False
5154

5255
# Prefix each autosectionlabel with the name of the document it is in and a colon
5356
autosectionlabel_prefix_document = True
@@ -222,3 +225,42 @@ def setup(app):
222225
img_path=img_path
223226
)
224227
)
228+
229+
app.connect('autodoc-process-docstring', doc_coverage)
230+
app.connect('build-finished', doc_report)
231+
232+
233+
members_to_watch = ['module', 'class', 'function', 'exception', 'method', 'attribute']
234+
doc_count = 0
235+
undoc_count = 0
236+
undoc_objects = []
237+
undoc_print_objects = False
238+
239+
240+
def doc_coverage(app, what, name, obj, options, lines):
241+
global doc_count
242+
global undoc_count
243+
global undoc_objects
244+
245+
if (what in members_to_watch and len(lines) == 0):
246+
# blank docstring detected
247+
undoc_count += 1
248+
undoc_objects.append(name)
249+
else:
250+
doc_count += 1
251+
252+
253+
def doc_report(app, exception):
254+
global doc_count
255+
global undoc_count
256+
global undoc_objects
257+
# print out report of documentation coverage
258+
total_docs = undoc_count + doc_count
259+
if total_docs != 0:
260+
print(f'\nAPI Doc coverage of {doc_count/total_docs:.1%}')
261+
if undoc_print_objects or os.environ.get('READTHEDOCS'):
262+
print('\nItems lacking documentation')
263+
print('===========================')
264+
print(*undoc_objects, sep='\n')
265+
else:
266+
print('No docs counted, run \'make clean\' then rebuild to get the count.')

0 commit comments

Comments
 (0)