Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 6 commits into from
May 16, 2023
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ab72b67
docs: Correct 'tensorflow' typo in v0.7.1 release notes
matthewfeickert May 11, 2023
690b7d4
backport dev information
matthewfeickert May 16, 2023
b6de9c1
Backport removal of pylab
matthewfeickert May 16, 2023
539a5f2
docs: Use 'req@url' syntax to install from remote VCS (2115)
matthewfeickert Feb 14, 2023
7adb037
extend quotes
matthewfeickert May 16, 2023
58cb77e
Use all extra and 3.11 runtime
matthewfeickert May 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
backport dev information
  • Loading branch information
@matthewfeickert
matthewfeickert committed May 16, 2023
commit 690b7d43756feffdeea33df0bafc8681e655f901
85 changes: 81 additions & 4 deletions docs/development.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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
-------

Expand Down Expand Up @@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -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
^^^^^^^
Expand All @@ -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
----------

Expand Down
22 changes: 11 additions & 11 deletions docs/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__...
Expand All @@ -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`
Expand Down