Initial pass at API docs for labscript #74
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
I think you may need to bump the sphinx version number in setup.cfg to have this build correctly (to at least 3.1.0, see sphinx-doc/sphinx#7536) |
|
Good catch! Everything seems to be working now. There are lots of holes since the docstring coverage is pretty low, but this should give a pretty good place to start from if we are happy with the general formatting. |
|
Method signatures for |
|
Oops. Turns out this is actually a bug of sphinx autodoc. It was fixed in 3.1.2. Bumped the version again to fix it. Edit: seems like this is only a partial fix since only some of the classes show their proper signatures. I'm still seeing issues with AnalogIn and DDS. Should I just keep bumping? It works properly in my build environment with 3.2.1. |
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
Fixes issue with using autosummary templates
This fixes issue where autodoc does not correctly handle decorated function signatures.
|
Rebased to master and bumped sphinx requirement to 3.2.1, which does finally fix all of the decorated function |
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.
be more consistent.
|
Finished a decent pass at the docstrings. Coverage is 98%. Ready to merge. |
dihm
added a commit
that referenced
this pull request
Dec 7, 2021
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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This relies on the recursive features and custom templates of the autosummary extension,
as described in this stackoverflow post. I think it actually looks pretty good, though the format is a departure from the rest of the docs so far.
I initially tried to abuse apidoc to do something more in line with what we currently have with the hand-made docs, but that proved essentially impossible without the aid of third-party packages that were deemed too complicated to add to sphinx directly.