Enable doc building workflow (#4)

* ci: Add skip variable to workflow that builds docs. * refactor: Update examples to pass linting. * ci: try to get docs to build in GitHub * ci: Only build package for official repo. * feat: Added more support for 70k scopes and 7k AWGs. * docs: Add security policy. * docs: Update security policy. * docs: Update default parallel process count. * docs: Update to use 4 cores by default when building docs. * ci: Update runner for doc build. * ci: Zip up doc build archive before uploading it. * ci: Disable testing on mac temporarily. * ci: Update zip file name. * test: Re-order doc tests. * ci: change doc build to attempt to get workflow to pass * ci: change doc build to attempt to get workflow to pass, bump build * ci: change doc build to attempt to get workflow to pass * ci: allow make * ci: change to doc dir * ci: switch to using sphinx-build for docs * test: Update doctests to use sphinx build instead of make. * test: switch from sphinx to sphinx-build * test: Use python instead of subprocess in doc tests. * test: Update requirements to see if pytest-html was the cause of the issues. * ci: print out stdout while running pytest * ci: Add block to save sphinx log. * ci: Add block to save sphinx log. * ci: drop down to two parallel processes when building docs * ci: Add docs and doc tests back to CI. * ci: reduce normal doc build to 3 procs * test: Lock version of pytest-html until it is updated to fix the file not found issue. * test: Update testing requirements to work around bug in pytest-html with relative html output file paths. Added a troubleshooting guide for future contributors.
tektronix · Sep 5, 2023 · afb5676 · afb5676
1 parent 5ae7252
commit afb5676
Show file tree

Hide file tree

Showing 49 changed files with 395 additions and 37 deletions.
diff --git a/.github/workflows/package-build.yml b/.github/workflows/package-build.yml
@@ -31,7 +31,7 @@ jobs:
 #    environment:
 #      name: test-pypi
 #      url: https://test.pypi.org/p/tm_devices
-#    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+#    if: github.repository == 'tektronix/tm_devices' && github.event_name == 'push' && github.ref == 'refs/heads/main'
 #    runs-on: ubuntu-latest
 #    needs: build-package
 #    steps:
@@ -51,7 +51,7 @@ jobs:
 #    environment:
 #      name: pypi
 #      url: https://pypi.org/p/tm_devices
-#    if: github.event.action == 'published'
+#    if: github.repository == 'tektronix/tm_devices' && github.event.action == 'published'
 #    runs-on: ubuntu-latest
 #    needs: build-package
 #    permissions:

diff --git a/.github/workflows/test-code.yml b/.github/workflows/test-code.yml
@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        platform: [ubuntu-latest, macos-latest, windows-latest]
+        platform: [ubuntu-latest, windows-latest]  # TODO: add "macos-latest" back to the platform list
         python-version: ['3.8', '3.9', '3.10', '3.11']
     steps:
       - uses: actions/checkout@v3
@@ -44,7 +44,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os_name: [ubuntu, macos, windows]
+        os_name: [ubuntu, windows]  # TODO: add "macos" back to the os_name list
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python

diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml
@@ -14,7 +14,7 @@ concurrency:
 jobs:
   # Test building the docs (html, linkcheck, doctest, coverage)
   test-docs:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest-4-cores
     strategy:
       fail-fast: false
       matrix:
@@ -36,11 +36,17 @@ jobs:
           python -m pip install --upgrade tox
       - name: Test
         run: tox -ve ${{ matrix.tox_env }}
+      - uses: thedoctor0/[email protected]
+        if: '!cancelled()'
+        with:
+          type: zip
+          filename: ${{ matrix.tox_env }}_results.zip
+          path: .results_${{ matrix.tox_env }}/
       - uses: actions/upload-artifact@v3
         if: '!cancelled()'
         with:
           name: artifact_${{ matrix.tox_env }}
-          path: .results_${{ matrix.tox_env }}/**
+          path: ${{ matrix.tox_env }}_results.zip
   # Check that all jobs passed
   check-docs-passed:
     if: always()

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -27,14 +27,14 @@ repos:
       - id: remove-tabs
       - id: forbid-tabs
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.24.1
+    rev: 0.26.3
     hooks:
       - id: check-readthedocs
       - id: check-dependabot
       - id: check-github-actions
       - id: check-github-workflows
   - repo: https://github.com/commitizen-tools/commitizen
-    rev: 3.6.0
+    rev: 3.7.0
     hooks:
       - id: commitizen
         stages: [commit-msg]
@@ -47,7 +47,7 @@ repos:
     hooks:
       - id: yamlfix
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.16
+    rev: 0.7.17
     hooks:
       - id: mdformat
         args: [--number, --end-of-line, keep]
@@ -60,6 +60,8 @@ repos:
           - mdformat-config
           - mdformat-shfmt
           - mdformat-web
+          - mdformat-gfm
+          - mdformat-footnote
 # Currently rstcheck doesn't work with the templates
 #  - repo: https://github.com/rstcheck/rstcheck
 #    rev: v6.1.2
@@ -112,7 +114,7 @@ repos:
         always_run: true
         args: [., --min=10]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.285
+    rev: v0.0.287
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,42 @@ project adheres to [Semantic Versioning](https://semver.org).
 
 ______________________________________________________________________
 
+## v0.1.11 (2023-08-29)
+
+### Added
+
+- Cache `*OPT?` on first access.
+
+______________________________________________________________________
+
+## v0.1.10 (2023-08-29)
+
+### Added
+
+- Support for AWG7KB
+
+______________________________________________________________________
+
+## v0.1.9 (2023-08-24)
+
+### Added
+
+- Support for `num_dig_bits_in_ch` and `total_channels` properties to TekScope5k7k70k.
+
+______________________________________________________________________
+
+## v0.1.8 (2023-08-09)
+
+### Added
+
+- Support for AWG5KB
+
+### Changed
+
+- Changed waveform generation to enforce CustomStrEnum function type.
+
+______________________________________________________________________
+
 ## v0.1.7 (2023-08-02)
 
 ### Added
@@ -20,6 +56,22 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## v0.1.6 (2023-07-25)
+
+### Changed
+
+- Fixed bug with not allowing empty license lists.
+
+______________________________________________________________________
+
+## v0.1.5 (2023-07-25)
+
+### Changed
+
+- Updated syntax for AFG polarities.
+
+______________________________________________________________________
+
 ## v0.1.4 (2023-07-21)
 
 ### Added
@@ -39,6 +91,32 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## v0.1.3 (2023-07-03)
+
+### Changed
+
+- Removed TRIANGLE from AFG function list.
+- Added symmetry to waveform generation function call.
+
+______________________________________________________________________
+
+## v0.1.2 (2023-06-27)
+
+### Changed
+
+- Updated the add_new dynamic item methods to work with numbers higher than 9.
+- Fixed malformed command syntax due to a bug in determining the preceding separator character.
+
+______________________________________________________________________
+
+## v0.1.1 (2023-06-20)
+
+### Added
+
+- Added support for .dev versions.
+
+______________________________________________________________________
+
 ## v0.1.0 (2022-08-08)
 
 ### Added

diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| > 0.1.0 | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Please reach out directly to the maintainers to report a
+potential vulnerability. **Do not file a public issue.**
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,7 +1,7 @@
 # Minimal makefile for Sphinx documentation
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W --keep-going -j 3
+SPHINXOPTS    = -W --keep-going -j 2
 SPHINXBUILD   = python -msphinx
 SPHINXPROJ    = tm_devices
 SOURCEDIR     = .

diff --git a/docs/conf.py b/docs/conf.py
@@ -172,6 +172,7 @@ def prep_jinja_env(jinja_env: JinjaEnvironment) -> None:
     "https://python-semantic-release.readthedocs.io/en/latest/",
     "https://docs.pytest.org/en/latest/",
     "https://pytest-cov.readthedocs.io/en/latest/",
+    "https://pytest-html.readthedocs.io/en/latest/",
     "https://pyvisa.readthedocs.io/projects/pyvisa-sim/en/latest/",
 ]
 tippy_anchor_parent_selector = "div.document"

diff --git a/docs/make.bat b/docs/make.bat
@@ -7,13 +7,15 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
     set SPHINXBUILD=python -msphinx
 )
-set SOURCEDIR=.
+if "%SOURCEDIR%" == "" (
+    set SOURCEDIR=.
+)
 if "%BUILDDIR%" == "" (
     set BUILDDIR=_build
 )
 set SPHINXPROJ=tm_devices
 if "%SPHINXOPTS%" == "" (
-    set SPHINXOPTS=-W --keep-going -j 3
+    set SPHINXOPTS=-W --keep-going -j 2
 )
 
 if "%1" == "" goto help

diff --git a/docs/troubleshooting/contributions.md b/docs/troubleshooting/contributions.md
@@ -223,3 +223,113 @@ python -m poetry update
 
 # Re-run original, failing command
 ```
+
+______________________________________________________________________
+
+## `FileNotFoundError` when running tests
+
+### Problem:
+
+When running tests with a specified html output file, sometimes an internal error
+can be raised causing the test run to crash.
+
+```console
+> pytest -k "test_docs" --self-contained-html --html=.results_doctests/results.html
+
+platform win32 -- Python 3.11.4, pytest-7.4.1, pluggy-1.3.0 -- .env\Scripts\python.exe
+cachedir: .pytest_cache
+metadata: {'Python': '3.11.4', 'Platform': 'Windows-10-10.0.19045-SP0', 'Packages': {'pytest': '7.4.1', 'pluggy': '1.3.0'}, 'Plugins': {'cov': '4.1.0', 'html': '4.0.0', 'metadata': '3.0.0', 'order': '1.1.0', 'profiling': '1.7.0'}}
+configfile: pyproject.toml
+plugins: cov-4.1.0, html-4.0.0, metadata-3.0.0, order-1.1.0, profiling-1.7.0
+collected 177 items / 174 deselected / 3 selected
+
+tests/test_docs.py::TestDocs::test_docs_linkcheck                                                                                                                                                                                                   [ 33%]
+INTERNALERROR> Traceback (most recent call last):
+INTERNALERROR>   File ".env\Lib\site-packages\_pytest\main.py", line 270, in wrap_session
+INTERNALERROR>     session.exitstatus = doit(config, session) or 0
+INTERNALERROR>                          ^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\_pytest\main.py", line 324, in _main
+INTERNALERROR>     config.hook.pytest_runtestloop(session=session)
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_hooks.py", line 493, in __call__
+INTERNALERROR>     return self._hookexec(self.name, self._hookimpls, kwargs, firstresult)
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_manager.py", line 115, in _hookexec
+INTERNALERROR>     return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_callers.py", line 152, in _multicall
+INTERNALERROR>     return outcome.get_result()
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_result.py", line 114, in get_result
+INTERNALERROR>     raise exc.with_traceback(exc.__traceback__)
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_callers.py", line 77, in _multicall
+INTERNALERROR>     res = hook_impl.function(*args)
+INTERNALERROR>           ^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\_pytest\main.py", line 349, in pytest_runtestloop
+INTERNALERROR>     item.config.hook.pytest_runtest_protocol(item=item, nextitem=nextitem)
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_hooks.py", line 493, in __call__
+INTERNALERROR>     return self._hookexec(self.name, self._hookimpls, kwargs, firstresult)
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_manager.py", line 115, in _hookexec
+INTERNALERROR>     return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_callers.py", line 152, in _multicall
+INTERNALERROR>     return outcome.get_result()
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_result.py", line 114, in get_result
+INTERNALERROR>     raise exc.with_traceback(exc.__traceback__)
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_callers.py", line 77, in _multicall
+INTERNALERROR>     res = hook_impl.function(*args)
+INTERNALERROR>           ^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\_pytest\runner.py", line 114, in pytest_runtest_protocol
+INTERNALERROR>     runtestprotocol(item, nextitem=nextitem)
+INTERNALERROR>   File ".env\Lib\site-packages\_pytest\runner.py", line 133, in runtestprotocol
+INTERNALERROR>     reports.append(call_and_report(item, "call", log))
+INTERNALERROR>                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\_pytest\runner.py", line 226, in call_and_report
+INTERNALERROR>     hook.pytest_runtest_logreport(report=report)
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_hooks.py", line 493, in __call__
+INTERNALERROR>     return self._hookexec(self.name, self._hookimpls, kwargs, firstresult)
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_manager.py", line 115, in _hookexec
+INTERNALERROR>     return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_callers.py", line 113, in _multicall
+INTERNALERROR>     raise exception.with_traceback(exception.__traceback__)
+INTERNALERROR>   File ".env\Lib\site-packages\pluggy\_callers.py", line 77, in _multicall
+INTERNALERROR>     res = hook_impl.function(*args)
+INTERNALERROR>           ^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File ".env\Lib\site-packages\pytest_html\basereport.py", line 251, in pytest_runtest_logreport
+INTERNALERROR>     self._generate_report()
+INTERNALERROR>   File ".env\Lib\site-packages\pytest_html\selfcontained_report.py", line 39, in _generate_report
+INTERNALERROR>     super()._generate_report(self_contained=True)
+INTERNALERROR>   File ".env\Lib\site-packages\pytest_html\basereport.py", line 65, in _generate_report
+INTERNALERROR>     self._write_report(rendered_report)
+INTERNALERROR>   File ".env\Lib\site-packages\pytest_html\basereport.py", line 134, in _write_report
+INTERNALERROR>     with self._report_path.open("w", encoding="utf-8") as f:
+INTERNALERROR>          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR>   File "C:\Python311_64bit\Lib\pathlib.py", line 1044, in open
+INTERNALERROR>     return io.open(self, mode, buffering, encoding, errors, newline)
+INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+INTERNALERROR> FileNotFoundError: [Errno 2] No such file or directory: '.results_doctests\\results.html'
+
+```
+
+### Solution:
+
+This is caused by passing in a relative path to the html output file via the `--html` flag. Some
+versions of [`pytest-html`](https://pytest-html.readthedocs.io/en/latest/index.html) don't convert
+the path to an absolute path, so if a test changes the current working directory the html
+reporter plugin will raise a `FileNotFoundError`.
+
+In order to prevent this issue from occurring, simply pass in the full path to the html output
+file when running pytest.
+
+```console
+# Linux
+source .env/bin/activate
+pytest -k "test_docs" --self-contained-html --html=$(pwd)/.results_doctests/results.html
+
+# Windows
+.env\Scripts\activate.bat
+pytest -k "test_docs" --self-contained-html --html=%CD%\.results_doctests\results.html
+```
diff --git a/examples/source_measure_units/2600/smu_2600_bjt_slow.py b/examples/source_measure_units/2600/smu_2600_bjt_slow.py
@@ -293,7 +293,7 @@ def display_results(sep: str = "\t") -> None:
     print("")
     print("BJT Slow Complete. Results: ")
     print("VCEO", "VCEsat", "VBEsat", "BETA1", "STATUS", sep=sep)
-    for index in range(0, NUM_PARTS):
+    for index in range(NUM_PARTS):
         status_str = "Pass" if status_data[index] else "Fail"
         print(
             f"{vceo_data[index]:.2e}",

diff --git a/examples/source_measure_units/2600/smu_2600_diode_test_fast.py b/examples/source_measure_units/2600/smu_2600_diode_test_fast.py
@@ -165,7 +165,7 @@ def diode_test(inst: SMU2602B) -> None:
 
     inst.commands.smu["a"].source.output = inst.commands.smu["a"].OUTPUT_ON
 
-    for index in range(0, NDIODES):
+    for index in range(NDIODES):
         # Perform Forward Voltage Test #1 (Vf1)
         vf1_test_volt[index], vf1_test_curr[index] = vfwd_vrev(
             inst, VF1_ISRC_RNG, VF1_ISRC_LEV, VF1_SRC_DEL, VF1_VCMPL
@@ -410,7 +410,7 @@ def display_bins_status() -> None:
     """Used to display the counts for each bin."""
     print("Bin Counts: ")
     display_str = ""
-    for index in range(0, 7):
+    for index in range(7):
         display_str += str(bins[index]) + " "
     print(display_str)