Merge pull request #49 from qutip/feature/add-build-workflows

Add build and documentation build workflows.

.github/workflows/build.yml

@@ -0,0 +1,170 @@
+name: Build wheels, optionally deploy to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm_ref:
+        description: "Confirm chosen branch name to deploy to PyPI (optional):"
+        default: ""
+      override_version:
+        description: "Override version number (optional):"
+        default: ""
+
+
+jobs:
+  # The deploy_test job is part of the test of whether we should deploy to PyPI.
+  # The job will succeed if either the confirmation reference is empty or if the
+  # confirmation is the selected branch or tag name.  It will fail if it is
+  # nonempty and does not match.  All later jobs depend on this job, so that
+  # they will be immediately cancelled if the confirmation is bad.  The
+  # dependency is currently necessary (2021-03) because GitHub Actions does not
+  # have a simpler method of cancelling an entire workflow---the normal use-case
+  # expects to try and run as much as possible despite one or two failures.
+  deploy_test:
+    name: Verify PyPI deployment confirmation
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_REF: ${{ github.ref }}
+      CONFIRM_REF: ${{ github.event.inputs.confirm_ref }}
+    steps:
+      - name: Compare confirmation to current reference
+        shell: bash
+        run: |
+          [[ -z $CONFIRM_REF || $GITHUB_REF =~ ^refs/(heads|tags)/$CONFIRM_REF$ ]]
+          if [[ -z $CONFIRM_REF ]]; then
+            echo "Build only.  Nothing will be uploaded to PyPI."
+          else
+            echo "Full build and deploy.  Wheels and source will be uploaded to PyPI."
+          fi
+
+
+  build_sdist:
+    name: Build sdist on Ubuntu
+    needs: deploy_test
+    runs-on: ubuntu-latest
+    env:
+      OVERRIDE_VERSION: ${{ github.event.inputs.override_version }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          # For the sdist we should be as conservative as possible with our
+          # Python version.  This should be the lowest supported version.  This
+          # means that no unsupported syntax can sneak through.
+          python-version: '3.6'
+
+      - name: Install pip build
+        run: |
+          python -m pip install 'build'
+
+      - name: Build sdist tarball
+        shell: bash
+        run: |
+          if [[ ! -z "$OVERRIDE_VERSION" ]]; then echo "$OVERRIDE_VERSION" > VERSION; fi
+          # The build package is the reference PEP 517 package builder.  All
+          # dependencies are specified by our setup code.
+          python -m build --sdist .
+
+      # Zip files are not part of PEP 517, so we need to make our own.
+      - name: Create zipfile from tarball
+        shell: bash
+        working-directory: dist
+        run: |
+          # First assert that there is exactly one tarball, and find its name.
+          shopt -s failglob
+          tarball_pattern="*.tar.gz"
+          tarballs=($tarball_pattern)
+          [[ ${#tarballs[@]} == 1 ]]
+          tarball="${tarballs[0]}"
+          # Get the stem and make the zipfile name.
+          stem="${tarball%.tar.gz}"
+          zipfile="${stem}.zip"
+          # Extract the tarball and rezip it.
+          tar -xzf "$tarball"
+          zip "$zipfile" -r "$stem"
+          rm -r "$stem"
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: sdist
+          path: |
+            dist/*.tar.gz
+            dist/*.zip
+          if-no-files-found: error
+
+
+  build_wheels:
+    name: Build wheels
+    needs: deploy_test
+    runs-on: ubuntu-latest
+    env:
+      OVERRIDE_VERSION: ${{ github.event.inputs.override_version }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          # This is about the build environment, not the released wheel version.
+          python-version: '3.7'
+
+      - name: Install pip build
+        run: |
+          python -m pip install 'build'
+
+      - name: Build wheels
+        shell: bash
+        run: |
+          # If the version override was specified, then write it the VERSION
+          # file with it.
+          if [[ ! -z "$OVERRIDE_VERSION" ]]; then echo "$OVERRIDE_VERSION" > VERSION; fi
+          # The build package is the reference PEP 517 package builder.  All
+          # dependencies are specified by our setup code.
+          python -m build --wheel --outdir wheelhouse .
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: wheels
+          path: ./wheelhouse/*.whl
+
+
+  deploy:
+    name: "Deploy to PyPI if desired"
+    # The confirmation is tested explicitly in `deploy_test`, so we know it is
+    # either a missing confirmation (so we shouldn't run this job) or a valid
+    # confirmation.  We don't need to retest the value of the confirmation,
+    # beyond checking that one existed.
+    if: ${{ github.event.inputs.confirm_ref != '' }}
+    needs: [deploy_test, build_sdist, build_wheels]
+    runs-on: ubuntu-latest
+    env:
+      TWINE_USERNAME: __token__
+      TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+      TWINE_NON_INTERACTIVE: 1
+      TWINE_REPOSITORY: pypi
+
+    steps:
+      - name: Download build artifacts to local runner
+        uses: actions/download-artifact@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: '3.7'
+
+      - name: Verify this is not a dev version
+        shell: bash
+        run: |
+          python -m pip install wheels/*.whl
+          python -c 'import qutip_qip; print(qutip_qip.__version__); assert "dev" not in qutip_qip.__version__; assert "+" not in qutip_qip.__version__'
+
+      # We built the zipfile for convenience distributing to Windows users on
+      # our end, but PyPI only needs the tarball.
+      - name: Upload sdist and wheels to PyPI
+        run: |
+          python -m pip install "twine"
+          python -m twine upload --verbose wheels/*.whl sdist/*.tar.gz

.github/workflows/build_documentation.yml

@@ -0,0 +1,46 @@
+name: Build HTML documentation
+
+on:
+  [push, pull_request]
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: '3.8'
+
+      - name: Install documentation dependencies
+        run: |
+          python -mpip install -r doc/requirements.txt
+
+      - name: Install qutip-qip from GitHub
+        run: |
+          python -mpip install -e .[full]
+          # Install in editable mode so it doesn't matter if we import from
+          # inside the installation directory, otherwise we can get some errors
+          # because we're importing from the wrong location.
+          python -c 'import qutip_qip; print("QuTiP QIP Version:      %s" % qutip_qip.__version__)'
+          python -c 'import qutip; qutip.about()'
+
+      - name: Build documentation
+        working-directory: doc
+        run: |
+          make html SPHINXOPTS="-W --keep-going -T"
+          # Above flags are:
+          #   -W : turn warnings into errors
+          #   --keep-going : do not stop after the first error
+          #   -T : display a full traceback if a Python exception occurs
+
+      - name: Upload built files
+        uses: actions/upload-artifact@v2
+        with:
+          name: qutip_qip_html_docs
+          path: doc/_build/html/*
+          if-no-files-found: error

.github/workflows/test.yml

@@ -32,7 +32,7 @@ jobs:
 
   doctest:
     runs-on: ubuntu-latest
-        
+
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python
@@ -47,10 +47,10 @@ jobs:
         pip install .
     - name: Test code snippets in the documentation
       run: |
-        cd docs
+        cd doc
         make doctest
     - name: Test code examples for the pulse paper
       run: |
         python -m pip install joblib pytest pytest-custom_exit_code
-        cd docs/pulse-paper
+        cd doc/pulse-paper
         pytest *.py --suppress-no-test-exit-code

.gitignore

@@ -71,7 +71,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -2,14 +2,14 @@
 
 version: 2
 
-# Build from the docs/ directory with Sphinx
+# Build from the doc/ directory with Sphinx
 sphinx:
-  configuration: docs/source/conf.py
+  configuration: doc/source/conf.py
 
 # Explicitly set the version of Python and its requirements
 python:
   version: 3.8
   install:
-    - requirements: docs/requirements.txt
+    - requirements: doc/requirements.txt
     - method: pip
       path: .

README.md

@@ -32,11 +32,11 @@ Documentation and tutorials
 
 The documentation of `qutip-qip` updated to the latest development version is hosted at [qutip-qip.readthedocs.io/](https://qutip-qip.readthedocs.io/en/latest/).
 
-Code examples used in the preprint [*Pulse-level noisy quantum circuits with QuTiP*](https://arxiv.org/abs/2105.09902), updated for the latest code version, are hosted in [this folder](https://github.com/qutip/qutip-qip/tree/master/docs/pulse-paper).
+Code examples used in the preprint [*Pulse-level noisy quantum circuits with QuTiP*](https://arxiv.org/abs/2105.09902), updated for the latest code version, are hosted in [this folder](https://github.com/qutip/qutip-qip/tree/master/doc/pulse-paper).
 
 Installation from source
 ------------------------
-If you want to edit the source code, please download the source code and run the following command under the root `qutip-qip` folder, 
+If you want to edit the source code, please download the source code and run the following command under the root `qutip-qip` folder,
 ```
 pip install --upgrade pip
 pip install -e .
@@ -49,7 +49,7 @@ To build and test the documentation, additional packages need to be installed:
 pip install matplotlib sphinx numpydoc sphinx_rtd_theme
 ```
 
-Under the `docs` directory, use
+Under the `doc` directory, use
 ```
 make html
 ```

VERSION

@@ -0,0 +1 @@
+0.2.0.dev

docs/Makefile → doc/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/make.bat → doc/make.bat

@@ -8,7 +8,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
-set BUILDDIR=build
+set BUILDDIR=_build
 
 if "%1" == "" goto help
 

docs/requirements.txt → doc/requirements.txt

@@ -7,3 +7,4 @@ sphinx_rtd_theme==0.5.1
 readthedocs-sphinx-search==0.1.0rc3
 numpydoc==1.1.0
 matplotlib==3.3.4
+docutils==0.16

docs/source/conf.py → doc/source/conf.py

@@ -11,6 +11,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import pathlib
 import sys
 sys.path.insert(0, os.path.abspath('.'))
 
@@ -21,8 +22,24 @@
 copyright = '2021, QuTiP Community'
 author = 'QuTiP Community'
 
-# The full version, including alpha/beta/rc tags
-release = '0.1.0dev'
+
+def qutip_qip_version():
+    """ Retrieve the qutip-qip version from ``../../VERSION``.
+    """
+    src_folder_root = pathlib.Path(__file__).absolute().parent.parent.parent
+    version = src_folder_root.joinpath(
+        "VERSION"
+    ).read_text().strip()
+    return version
+
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+# The full version, including alpha/beta/rc tags.
+release = qutip_qip_version()
+# The short X.Y version.
+version = ".".join(release.split(".")[:2])
 
 
 # -- General configuration ---------------------------------------------------
@@ -61,7 +78,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -145,4 +162,4 @@
 
 numpydoc_show_class_members = False
 napoleon_numpy_docstring = True
-napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_notes = True