docs(backport): Add dev instructions and fix typos (#2206)

* Backport components of:
   - PR #2046
   - PR #2098
   - PR #2113
   - PR #2115
   - PR #2145
   - PR #2198

CONTRIBUTING.md

@@ -55,7 +55,7 @@ We recommend first reading the "[Developing](https://scikit-hep.org/pyhf/develop
 You can install the development environment (which includes a number of extra) libraries and all others needed to run the tests via `pip`:
 
 ```console
-python -m pip install --upgrade --editable .[complete]
+python -m pip install --upgrade --editable '.[develop]'
 ```
 
 To make the PR process much smoother we also strongly recommend that you setup the Git pre-commit hook for [Black](https://github.com/psf/black) by running

binder/postBuild

@@ -1,2 +1,2 @@
-python -m pip install --upgrade .[complete]
+python -m pip install --upgrade '.[all]'
 python -m pip install altair

binder/runtime.txt

@@ -1 +1 @@
-python-3.10
+python-3.11

docs/development.rst

@@ -7,7 +7,7 @@ Developer Environment
 
 To develop, we suggest using Python `virtual environments
 <https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments>`__
-together with ``pip``.
+together with ``pip`` and steered by `nox <https://github.com/wntrblm/nox>`__.
 Once the virtual environment is activated and you have `SSH keys setup with GitHub
 <https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`__, clone the
 repo from GitHub
@@ -20,7 +20,7 @@ and install all necessary packages for development
 
 .. code-block:: console
 
-    python -m pip install --upgrade --editable .[complete]
+    python -m pip install --upgrade --editable '.[develop]'
 
 Then setup the Git `pre-commit <https://pre-commit.com/>`__ hooks by running
 
@@ -33,6 +33,30 @@ inside of the virtual environment.
 through time, so pre-commit will automatically update itself when you run it
 locally after the hooks were updated.
 
+It is then suggested that you use ``nox`` to actually run all development operations
+in "sessions" defined in ``noxfile.py``.
+To list all of the available sessions run
+
+.. code-block:: console
+
+    nox --list
+
+Linting
+-------
+
+Linting and code formatting is handled by ``pre-commit``.
+To run the linting either run ``pre-commit``
+
+.. code-block:: console
+
+    pre-commit run --all-files
+
+or use ``nox``
+
+.. code-block:: console
+
+    nox --session lint
+
 Testing
 -------
 
@@ -73,7 +97,7 @@ contrib module, or notebooks, and so instead to test the core codebase a develop
 
 .. code-block:: console
 
-    pytest --ignore tests/benchmarks/ --ignore tests/contrib --ignore tests/test_notebooks.py
+    nox --session tests --python 3.11
 
 Contrib module matplotlib image tests
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -83,7 +107,14 @@ To run the visualization tests for the ``contrib`` module with the ``pytest-mpl`
 
 .. code-block:: console
 
-    pytest tests/contrib --mpl --mpl-baseline-path tests/contrib/baseline --mpl-generate-summary html
+    nox --session tests --python 3.11 -- contrib
+
+If the image files need to be regenerated, run the tests with the
+``--mpl-generate-path=tests/contrib/baseline`` option or just run
+
+.. code-block:: console
+
+    nox --session regenerate
 
 Doctest
 ^^^^^^^
@@ -97,6 +128,52 @@ For example, to run ``doctest`` on the JAX backend run
 
     pytest src/pyhf/tensor/jax_backend.py
 
+Coverage
+~~~~~~~~
+
+To measure coverage for the codebase run the tests under ``coverage`` with
+
+.. code-block:: console
+
+    coverage run --module pytest
+
+or pass ``coverage`` as a positional argument to the ``nox`` ``tests`` session
+
+.. code-block:: console
+
+    nox --session tests --python 3.11 -- coverage
+
+Coverage Report
+^^^^^^^^^^^^^^^
+
+To generate a coverage report after running the tests under ``coverage`` run
+
+.. code-block:: console
+
+    coverage
+
+or to also generate XML and HTML versions of the report run the coverage ``nox`` session
+
+.. code-block:: console
+
+    nox --session coverage
+
+Documentation
+-------------
+
+To build the docs run
+
+.. code-block:: console
+
+    nox --session docs
+
+To view the built docs locally, open the resulting ``docs/_build/html/index.html`` file
+in a web browser or run
+
+.. code-block:: console
+
+    nox --session docs -- serve
+
 Publishing
 ----------
 

docs/examples/notebooks/learn/InterpolationCodes.ipynb

@@ -4,19 +4,11 @@
    "cell_type": "code",
    "execution_count": 1,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Populating the interactive namespace from numpy and matplotlib\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
-    "%pylab inline\n",
-    "from ipywidgets import interact\n",
     "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "from ipywidgets import interact\n",
     "from mpl_toolkits.mplot3d import Axes3D"
    ]
   },

docs/installation.rst

@@ -32,36 +32,36 @@ Install latest stable release from `PyPI <https://pypi.org/project/pyhf/>`__...
 
 .. code-block:: console
 
-    python -m pip install pyhf[tensorflow]
+    python -m pip install 'pyhf[tensorflow]'
 
 ... with PyTorch backend
 ++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[torch]
+    python -m pip install 'pyhf[torch]'
 
 ... with JAX backend
 ++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[jax]
+    python -m pip install 'pyhf[jax]'
 
 ... with all backends
 +++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[backends]
+    python -m pip install 'pyhf[backends]'
 
 
 ... with xml import/export functionality
 ++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[xmlio]
+    python -m pip install 'pyhf[xmlio]'
 
 
 Install latest development version from `GitHub <https://github.com/scikit-hep/pyhf>`__...
@@ -72,43 +72,43 @@ Install latest development version from `GitHub <https://github.com/scikit-hep/p
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf"
+    python -m pip install --upgrade 'pyhf@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with TensorFlow backend
 +++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[tensorflow]"
+    python -m pip install --upgrade 'pyhf[tensorflow]@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with PyTorch backend
 ++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[torch]"
+    python -m pip install --upgrade 'pyhf[torch]@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with JAX backend
 ++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[jax]"
+    python -m pip install --upgrade 'pyhf[jax]@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with all backends
 +++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[backends]"
+    python -m pip install --upgrade 'pyhf[backends]@git+https://github.com/scikit-hep/pyhf.git'
 
 
 ... with xml import/export functionality
 ++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[xmlio]"
+    python -m pip install --upgrade 'pyhf[xmlio]@git+https://github.com/scikit-hep/pyhf.git'
 
 
 Updating :code:`pyhf`

docs/release-notes/v0.7.1.rst

@@ -9,7 +9,7 @@ Important Notes
 * All backends are now fully compatible and tested with
   `Python 3.11 <https://peps.python.org/pep-0664/>`_.
   (PR :pr:`2145`)
-* The ``tensorflow`` extra (``'pyhf[tensorlfow]'``) now automatically installs
+* The ``tensorflow`` extra (``'pyhf[tensorflow]'``) now automatically installs
   ``tensorflow-macos`` for Apple silicon machines.
   (PR :pr:`2119`)
 

src/pyhf/cli/complete.py

@@ -21,9 +21,9 @@ def cli(shell):
     @click.command(help='Generate shell completion code.', name='completions')
     @click.argument('shell', default=None)
     def cli(shell):
-        '''Placeholder for shell completion code generatioon function if necessary dependency is missing.'''
+        """Placeholder for shell completion code generatioon function if necessary dependency is missing."""
         click.secho(
-            'This requires the click_completion module.\n'
-            'You can install it with the shellcomplete extra:\n'
-            'python -m pip install pyhf[shellcomplete]'
+            "This requires the click_completion module.\n"
+            "You can install it with the shellcomplete extra:\n"
+            "python -m pip install 'pyhf[shellcomplete]'"
         )

src/pyhf/cli/rootio.py

@@ -50,7 +50,7 @@ def xml2json(
     except ImportError:
         log.error(
             "xml2json requires uproot, please install pyhf using the "
-            "xmlio extra: python -m pip install pyhf[xmlio]",
+            "xmlio extra: python -m pip install 'pyhf[xmlio]'",
             exc_info=True,
         )
     from pyhf import readxml
@@ -86,7 +86,7 @@ def json2xml(workspace, output_dir, specroot, dataroot, resultprefix, patch):
     except ImportError:
         log.error(
             "json2xml requires uproot, please install pyhf using the "
-            "xmlio extra: python -m pip install pyhf[xmlio]",
+            "xmlio extra: python -m pip install 'pyhf[xmlio]'",
             exc_info=True,
         )
     from pyhf import writexml

src/pyhf/contrib/cli.py

@@ -24,7 +24,7 @@ def cli():
 
         .. code-block:: shell
 
-            $ python -m pip install pyhf[contrib]
+            $ python -m pip install 'pyhf[contrib]'
     """
     from pyhf.contrib import utils  # Guard CLI from missing extra # noqa: F401
 
@@ -72,6 +72,6 @@ def download(archive_url, output_directory, verbose, force, compress):
     except AttributeError:
         log.error(
             "\nInstallation of the contrib extra is required to use the contrib CLI API"
-            + "\nPlease install with: python -m pip install pyhf[contrib]\n",
+            + "\nPlease install with: python -m pip install 'pyhf[contrib]'\n",
             exc_info=True,
         )

src/pyhf/contrib/utils.py

@@ -128,6 +128,6 @@ def download(archive_url, output_directory, force=False, compress=False):
 except ModuleNotFoundError:
     log.error(
         "\nInstallation of the contrib extra is required to use pyhf.contrib.utils.download"
-        + "\nPlease install with: python -m pip install pyhf[contrib]\n",
+        + "\nPlease install with: python -m pip install 'pyhf[contrib]'\n",
         exc_info=True,
     )

tests/test_scripts.py

@@ -632,7 +632,7 @@ def test_missing_contrib_extra(caplog):
         for line in [
             "import of requests halted; None in sys.modules",
             "Installation of the contrib extra is required to use pyhf.contrib.utils.download",
-            "Please install with: python -m pip install pyhf[contrib]",
+            "Please install with: python -m pip install 'pyhf[contrib]'",
         ]:
             assert line in caplog.text
         caplog.clear()
@@ -672,7 +672,7 @@ def test_missing_contrib_download(caplog):
             for line in [
                 "module 'pyhf.contrib.utils' has no attribute 'download'",
                 "Installation of the contrib extra is required to use the contrib CLI API",
-                "Please install with: python -m pip install pyhf[contrib]",
+                "Please install with: python -m pip install 'pyhf[contrib]'",
             ]:
                 assert line in caplog.text
             caplog.clear()