Merge pull request #82 from dihm/myst_docs

dihm · web-flow · commit e99a74b5d69c · 2024-01-16T15:29:43.000-05:00
Update RTD builds
diff --git a/docs/source/archive.md b/docs/source/archive.md
@@ -1,4 +1,4 @@
-## BitBucket archive
+# BitBucket archive
 
 In April–May 2020 the _labscript suite_ code base was migrated from BitBucket to GitHub. All commit history and issues was preserved, however some repository metadata (such as pull request discussions) could not be migrated directly. As such, we have created an archived copy of everything that was on BitBucket. This includes:
 
@@ -10,15 +10,15 @@ In April–May 2020 the _labscript suite_ code base was migrated from BitBucket
 This archive can be found at [bitbucket-archive.labscriptsuite.org](https://bitbucket-archive.labscriptsuite.org/) (this page can take some time to load for the first time). Copies of every public fork of our repositories are at [github.com/labscript-suite-bitbucket-archive](https://github.com/labscript-suite-bitbucket-archive). As this is an archive, we will not be transferring ownership of these repositories back to their original owners. However, should you wish to continue development on one of those repositories you can fork it into your own account through the GitHub web interface. Should you have uncommitted changes (or changes made after 1st February, 2020) that you wish to have archived, please contact us to discuss the best approach to including these. Please note that we are not recommending continuing development in such forks long term, due to the changes in package structure outlined above.
 
 
-### What to do if you had custom code in a fork on BitBucket
+## What to do if you had custom code in a fork on BitBucket
 
-labscript experiment scripts and lyse analysis scripts can be copied or moved to the new labscriptlib/analysislib folders. We deem these user-side code as they are not within the codebase of the labcript suite programs, and thus do not require a [developer (editable) installation](../installation).
+labscript experiment scripts and lyse analysis scripts can be copied or moved to the new labscriptlib/analysislib folders. We deem these user-side code as they are not within the codebase of the labcript suite programs, and thus do not require a [developer (editable) installation](installation/index.rst).
 
-Customisations of the labscript suite will need to be reintegrated into the new package structure, using a developer installation. For example, to include your own custom labscript devices, you should undertake the developer installation procedure for the [labscript-devices](https://github.com/labscript-suite/labscript-devices) repository, and copy your custom or modified device files into the labscript_devices folder alongside the existing device files. Please also consider contributing these back to the main project by pushing them to your fork and [issuing a pull request](../contributing/#pull-requests).
+Customisations of the labscript suite will need to be reintegrated into the new package structure, using a developer installation. For example, to include your own custom labscript devices, you should undertake the developer installation procedure for the [labscript-devices](https://github.com/labscript-suite/labscript-devices) repository, and copy your custom or modified device files into the labscript_devices folder alongside the existing device files. Please also consider contributing these back to the main project by pushing them to your fork and [issuing a pull request](contributing.md/#pull-requests).
 
 The procedure for migrating customisations of other components will depend on how up-to-date your fork is. Please open a thread on the [mailing list](http://groups.google.com/group/labscriptsuite) to discuss with us how to migrate your custom features and/or how to contribute them back to the base _labscript suite_ repositories.
 
 
-### Migrating other repositories to GitHub
+## Migrating other repositories to GitHub
 
 Should you have other repositories on BitBucket such as labscriptlib, analysislib, userlib, or labconfig (or any project unrelated to the _labscript suite_) we strongly suggest using the tools we developed to migrate the _labscript suite_ to GitHub. These are [philipstarkey/bitbucket-hg-exporter](https://github.com/philipstarkey/bitbucket-hg-exporter) and [chrisjbillington/hg-export-tool](https://github.com/chrisjbillington/hg-export-tool) which can be used together. See the documentation of those projects for further details.
diff --git a/docs/source/building_docs/docs_comitting.rst b/docs/source/building_docs/docs_comitting.rst
@@ -11,7 +11,7 @@ The main difference is that documentation changes necessitate checking the read
 Making a PR
 -----------
 
-The general steps for creating the PR are outlined in :doc:`here <contributing>`. 
+The general steps for creating the PR are outlined in :doc:`here </contributing>`. 
 When making PRs with documentation changes, a few extra checks are required.
 In particular, it is a good idea to locally build the documentation as described :doc:`here <docs_build>`.
 If you cannot build locally, the docs will be built automatically for your PR by Read the Docs and can be viewed there (described below).
diff --git a/docs/source/changes.md b/docs/source/changes.md
@@ -1,8 +1,8 @@
-## Recent changes to the _labscript suite_
+# Recent changes to the _labscript suite_
 
 Upon migrating the code base to GitHub and publishing distributions on PyPI in April–May 2020, existing users should be aware of the following recent changes.
 
-### Profile directories
+## Profile directories
 
 The _labscript suite_ profile directory, containing application configurations, logs, and user-side code, is now located by default in the current user’s home directory, e.g. for a local user named `wkheisenberg` this is:
 
@@ -24,12 +24,12 @@ A typical structure of the profile directory is:
         └── user_devices/
 ```
 
-This structure is created by calling the command `labscript-profile-create` in a terminal after installing `labscript-utils` (per the [installation instructions](../installation)).
+This structure is created by calling the command `labscript-profile-create` in a terminal after installing `labscript-utils` (per the [installation instructions](installation/index.rst)).
 
 _Note:_ As of [labscript-suite/labscript-utils#37](https://github.com/labscript-suite/labscript-utils/issues/37) an editable installation can be located within the labscript-suite profile directory.
 
 
-### Secure communication
+## Secure communication
 
 Interprocess communication between components of the *labscript suite* is based on the [ZeroMQ](https://zeromq.org) (ZMQ) messaging protocol. We have supported secure interprocess communication via encrypted ZMQ messaging since February 2019 (labscript-utils 2.11.0).
 
@@ -62,17 +62,17 @@ allow_insecure = True
 * There is an outstanding issue with the ZMQ Python bindings on Windows ([zeromq/pyzmq#1148](https://github.com/zeromq/pyzmq/issues/1148)), whereby encryption is significantly slower for Python distributions other than [Anaconda](https://www.anaconda.com). Until this issue is resolved, we recommend that Windows users on an untrusted network use the Anaconda Python distribution (and install `pyzmq` using `conda install pyzmq`).
 
 
-### Application shortcuts
+## Application shortcuts
 
 Operating-system menu shortcuts, correct taskbar behaviour, and environment activation for the Python GUI applications (blacs, lyse, runmanager, and runviewer) is now handled by a standalone Python package [desktop-app](https://github.com/chrisjbillington/desktop-app) (per installation instructions above). This currently supports Windows and Linux (Mac OS X support is forthcoming).
 
 
-### Lab configuration
+## Lab configuration
 
 The `experiment_name` item has been renamed to `apparatus_name` in the labconfig (.ini) file, to better reflect the distinciton between the infrasturcture that experiment shots are executed on. The old keyword can still be used for this item, but a [warning](https://docs.python.org/3/library/exceptions.html#FutureWarning) will be issued to remind you to update your labconfig.
 
 
-### Source code structure (developer installation)
+## Source code structure (developer installation)
 
 Existing users who move to a developer (editable) installation, please note the following structural changes to the _labscript suite_ source code:
 
@@ -104,6 +104,6 @@ Existing users who move to a developer (editable) installation, please note the
 * As installation no longer requires a separate package, the repository formerly named ‘installer’ has been renamed to ‘[labscript-suite](https://github.com/labscript-suite/labscript-suite/issues)’, and is a metapackage for the *labscript suite* (installing it via `pip`/`conda` installs the suite).
 
 
-### Versioning (developer installation)
+## Versioning (developer installation)
 
-Aside from the maintenance branches described [here](../contributing/#branching-model-strategy), versions of the labscript suite packages are introspected at run-time using either the [importlib.metadata](importlib.metadata) library (regular installations) or [setuptools_scm](https://github.com/pypa/setuptools_scm) (developer installations). Thus any changes to an editable install will be traceable by local version numbers, e.g. editing the released version of a package with version 2.4.0 will result in 2.4.0dev1+gc28fe94, for example. This will help us diagnose issues users have with their editable installations.
+Aside from the maintenance branches described [here](contributing.md/#branching-modelstrategy), versions of the labscript suite packages are introspected at run-time using either the [importlib.metadata](importlib.metadata) library (regular installations) or [setuptools_scm](https://github.com/pypa/setuptools_scm) (developer installations). Thus any changes to an editable install will be traceable by local version numbers, e.g. editing the released version of a package with version 2.4.0 will result in 2.4.0dev1+gc28fe94, for example. This will help us diagnose issues users have with their editable installations.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -13,8 +13,6 @@
 import os
 from pathlib import Path
 import sys
-from m2r import MdInclude
-from recommonmark.transform import AutoStructify
 from jinja2 import FileSystemLoader, Environment
 
 # -- Project information (unique to each project) -------------------------------------
@@ -46,13 +44,14 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx_rtd_theme",
-    "recommonmark",
+    "myst_parser",
 ]
 
 autodoc_typehints = 'description'
 
 # Prefix each autosectionlabel with the name of the document it is in and a colon
 autosectionlabel_prefix_document = True
+myst_heading_anchors = 2
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -194,20 +193,7 @@
 # Use m2r only for mdinclude and recommonmark for everything else
 # https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992
 def setup(app):
-    config = {
-        # 'url_resolver': lambda url: github_doc_root + url,
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True,
-    }
-    app.add_config_value('recommonmark_config', config, True)
-    app.add_transform(AutoStructify)
-
-    # from m2r to make `mdinclude` work
-    app.add_config_value('no_underscore_emphasis', False, 'env')
-    app.add_config_value('m2r_parse_relative_links', False, 'env')
-    app.add_config_value('m2r_anonymous_references', False, 'env')
-    app.add_config_value('m2r_disable_inline_math', False, 'env')
-    app.add_directive('mdinclude', MdInclude)
+
     app.add_css_file('custom.css')
 
     # generate the components.rst file dynamically so it points to stable/latest
diff --git a/docs/source/contributing.md b/docs/source/contributing.md
@@ -1,9 +1,9 @@
-## Contributing to the _labscript suite_
+# Contributing to the _labscript suite_
 
 We are very grateful for all the contributions users have made in the past decade to make the _labscript suite_ the most widely used open-source experiment control and automation system in quantum science. These include development, suggestions, and feedback, and we look forward to this continuing on GitHub.
 
 
-### Issue tracking
+## Issue tracking
 
 The issue tracking on GitHub is very similar to BitBucket, with the added advantage that you can add inter-repository issue references, e.g. referring to [labscript-suite/runmanager#68](https://github.com/labscript-suite/runmanager/issues/68) in any issue or pull request will link to the corresponding issue. We have imported all issues from the BitBucket repositories into the GitHub repositories. This import is not perfect (as each comment is now posted by Phil Starkey) but the comments have been modified to contain the original author attribution. We have also updated all links to files, pull requests, issues, and commits so that they point to the equivalent GitHub location and/or the archived copy of the data (as discussed above).
 
@@ -16,12 +16,12 @@ Please use the issue tracker of the relevant GitHub repository for:
 For advice on _how_ to use the existing functionality of the _labscript suite_, please use our [mailing list](http://groups.google.com/group/labscriptsuite).
 
 
-### Request for developers
+## Request for developers
 
 We would like to reaffirm our invitation for users to directly contribute toward developing the _labscript suite_. We have established a separate discussion forum on Zulip for discussing development direction and design. If you are interested in being a part of these discussions, and/or testing and merging pull requests, please [reach out to us](mailto:labscriptsuite@gmail.com).
 
 
-### Pull requests
+## Pull requests
 
 We will continue the same feature-branch workflow as before.
 
@@ -61,7 +61,7 @@ The official GitHub documentation outlining this process is available [here](htt
 These steps are broadly covered in the GitHub [Hello World](https://guides.github.com/activities/hello-world/) guide, and in detail on the [NumPy development workflow](https://numpy.org/doc/stable/dev/development_workflow.html).
 
 
-### Branching model/strategy
+## Branching model/strategy
 
 The move to GitHub for source control and PyPI for distribution is accompanied by a slight change in the branching strategy, to improve deployment and stability of the _labscript suite_. Whereas before all versions corresponded to single commits on the master branch; dedicated branches will be used to release and service minor versions. For example, releasing v0.1.0 would see the creation of a branch named maintenance/0.1.x, used to service all 0.1 versions. As we adhere to [semantic versioning](https://semver.org/), bug-fixes would be applied in this branch, bumping the minor (final) version number each time, e.g. 0.1.1, 0.1.2, etc. No development will occur in these branches; new features are merged into master, and bug-fixes are cherry-picked from master.
 
@@ -72,7 +72,7 @@ You can learn more about this branching model at:
 * [Release Flow – Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/learn/devops-at-microsoft/release-flow)
 
 
-### Learning Git
+## Learning Git
 
 As our former development, installation, and upgrading practices involved Mercurial revision-control, some of you may not be familiar with Git. While you no longer need to use _any_ revision control system to use the _labscript suite_, those of you wanting to contribute to development who aren't acquainted with Git may benefit from these resources:
 
diff --git a/docs/source/features.md b/docs/source/features.md
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,6 +1,7 @@
 .. labscript suite documentation master file
 
-.. mdinclude:: main.md
+.. include:: main.md
+   :parser: myst_parser.sphinx_
 
 .. raw:: html
 
diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst
@@ -19,7 +19,6 @@ This makes it far easier to get started using the *labscript suite*, as you no l
     regular-anaconda
     developer-pypi
     developer-anaconda
-    .. regular-to-developer
 
 .. |pip| replace:: ``pip``
 .. _pip: https://packaging.python.org/tutorials/installing-packages
diff --git a/docs/source/main.md b/docs/source/main.md
@@ -1,8 +1,8 @@
 # the _labscript suite_
 
-### Experiment control and automation system
+_**Experiment control and automation system**_
 
-___
+---
 
 The _labscript suite_ is a powerful and extensible framework for experiment [composition](https://github.com/labscript-suite/labscript), [control](https://github.com/labscript-suite/runmanager), [execution](https://github.com/labscript-suite/blacs), and [analysis](https://github.com/labscript-suite/lyse). Developed for quantum science and quantum engineering; deployable in laboratory and in-field devices. Also applicable to optics, microscopy, materials engineering, biophysics, and any application predicated on the repetition of parameterised, hardware-timed experiments.
 
diff --git a/readthedocs.yaml b/readthedocs.yaml
@@ -4,6 +4,12 @@
 # Required
 version: 2
 
+# Set build environment options
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: dirhtml
@@ -15,9 +21,8 @@ formats:
   - pdf
   - epub
 
-# Optionally set the version of Python and requirements required to build your docs
+# Optionally set the requirements required to build your docs
 python:
-   version: 3.7
    install:
       - method: pip
         path: .
diff --git a/setup.cfg b/setup.cfg
@@ -44,9 +44,7 @@ spincore = spinapi
 nidaqmx = PyDAQmx
 nivision = PyNIVision
 docs = 
-  Sphinx==4.4.0
-  sphinx-rtd-theme==0.5.2
-  recommonmark==0.6.0
-  m2r==0.2.1
-  mistune<2.0.0
+  Sphinx==7.2.6
+  sphinx-rtd-theme==2.0.0
+  myst_parser==2.0.0
 
