updating docs and links and CI for building docs (#1014)

.github/workflows/coverage.yml

@@ -34,5 +34,5 @@ jobs:
         python-version: "3.12"
     - uses: yezz123/setup-uv@v4
     - run: uv pip install --system nox
-    - run: nox -s coverage
+    - run: nox -s cov
     - uses: AndreMiras/coveralls-python-action@develop

.github/workflows/docs.yml

@@ -32,7 +32,9 @@ jobs:
       with:
         python-version: "3.11"
     - run: sudo apt-get install pandoc
-    - run: make doc
+    - uses: yezz123/setup-uv@v4
+    - run: uv pip install --system nox
+    - run: nox -s doc
     - uses: actions/upload-pages-artifact@v3
       with:
         path: './build/html'

.github/workflows/test.yml

@@ -50,30 +50,3 @@ jobs:
     # python -m pip install .[test] is not used here to test minimum (faster),
     # the cov workflow runs all tests.
     - run: python -m pytest
-    # - run: |
-    #     pip uninstall -y numba
-    #     pip install --upgrade --pre numpy scipy matplotlib
-    #     python -m pytest
-    #   if: matrix.python-version == '3.11' || matrix.python-version == '3.12'
-
-  # aarch64:
-  #   runs-on: ubuntu-latest
-  #   env:
-  #     py: /opt/python/cp309-cp309/bin/python
-  #     img: quay.io/pypa/manylinux2014_aarch64
-  #   steps:
-  #   - uses: actions/checkout@v4
-  #     with:
-  #       submodules: true
-  #   - uses: docker/setup-qemu-action@v2
-  #   - run: >
-  #           docker run --rm -v ${{ github.workspace }}:/ws:rw --workdir=/ws
-  #           ${{ env.img }}
-  #           bash -exc '${{ env.py }} -m venv venv &&
-  #           source venv/bin/activate &&
-  #           python -m pip install --upgrade pip &&
-  #           python -m pip install . pytest'
-  #   - run: >
-  #           docker run --rm -v ${{ github.workspace }}:/ws:rw --workdir=/ws
-  #           ${{ env.img }}
-  #           venv/bin/python -m pytest

README.rst

@@ -108,7 +108,7 @@ When ``iminuit`` is used with cost functions that are JIT-compiled with `numba`_
 
 .. image:: doc/_static/roofit_vs_iminuit+numba.svg
 
-More information about this benchmark is given `in the Benchmark section of the documentation <https://scikit-hep.org/iminuit/benchmark.html#cost-function-benchmark>`_.
+More information about this benchmark is given `in the Benchmark section of the documentation <https://scikit-hep.org/iminuit/benchmark.html>`_.
 
 Partner projects
 ----------------
@@ -132,4 +132,4 @@ All interface changes are documented in the `changelog`_ with recommendations ho
 .. _numba_stats: https://github.com/HDembinski/numba-stats
 .. _boost-histogram: https://github.com/scikit-hep/boost-histogram
 .. _numba: https://numba.pydata.org
-.. _RooFit: https://root.cern.ch/doc/master/namespaceRooFit.html
+.. _RooFit: https://root.cern/manual/roofit/

doc/bibliography.txt

@@ -1,6 +1,5 @@
-.. _RooFit: https://root.cern.ch/master/namespaceRooFit.html
 .. _scipy: https://www.scipy.org/
-.. _scipy.optimize: https://docs.scipy.org/doc/scipy/reference/tutorial/optimize.html
+.. _scipy.optimize: https://docs.scipy.org/doc/scipy/tutorial/optimize.html
 .. _numba: https://numba.pydata.org
 .. _numba_stats: https://github.com/HDembinski/numba-stats
 .. _jax: https://jax.readthedocs.io
@@ -16,14 +15,15 @@
 .. _gammapy: https://github.com/gammapy/gammapy
 .. _flavio: https://github.com/flav-io/flavio
 .. _zfit: https://github.com/zfit/zfit
-.. _Minuit2: https://root.cern.ch/guides/minuit2-manual
+.. _Minuit2: https://root.cern.ch/root/htmldoc/guides/minuit2/Minuit2.html
 .. _PyMinuit: http://code.google.com/p/pyminuit
 .. _ipythonnb: http://ipython.org/ipython-doc/dev/notebook/index.html
-.. _Quasi Newton Method: http://en.wikipedia.org/wiki/Quasi-Newton_method
-.. _DFP formula: http://en.wikipedia.org/wiki/Davidon-Fletcher-Powell_formula
+.. _Quasi Newton Method: https://en.wikipedia.org/wiki/Quasi-Newton_method
+.. _DFP formula: https://en.wikipedia.org/wiki/Davidon-Fletcher-Powell_formula
 .. _Variable Metric Method for Minimization: https://www.osti.gov/biblio/4252678
 .. _A New Approach to Variable Metric Algorithm: http://comjnl.oxfordjournals.org/content/13/3/317.full.pdf+html
 .. _MINUIT paper: https://doi.org/10.1016/0010-4655(75)90039-9
 .. _setuptools: https://pypi.python.org/pypi/setuptools
 .. _pytest: http://pytest.org
 .. _zenodo: https://zenodo.org/record/4310361
+.. _RooFit: https://root.cern/manual/roofit/

doc/conf.py

@@ -82,3 +82,6 @@
     "--InlineBackend.figure_formats={'svg', 'pdf'}",
     "--InlineBackend.rc=figure.dpi=96",
 ]
+
+linkcheck_timeout = 3
+linkcheck_allow_unauthorized = True

doc/contribute.rst

@@ -37,53 +37,32 @@ It is a good idea to develop your feature in a separate branch, so that your dev
 
 Now you are in a feature branch, commit your edits here.
 
-venv
-++++
-
-You have the source code now, but you also want to build and test. We recommend to make a dedicated virtual environment for ``iminuit``, separate from the Python installation you use for other projects.
-
-The recommended way is to use `Python virtual environments`_ and ``pip``.
-
-.. code-block:: bash
-
-    python -m venv py3 # folders called py* are ignored by .gitignore
-    source py3/bin/activate
-    pip install -e '.[test]'
-
-To delete the virtual environment just delete the folder ``py3``.
-
 Development workflow
 --------------------
 
-To simplify hacking on OSX and Linux, we have a Makefile with common commands.
-
-Build ``iminuit`` in-place and run the tests:
+You have the source code now, but you also want to build and test. We recommend to use ``nox``, which automatically creates a dedicated virtual environment for ``iminuit``, separate from the Python installation you use for other projects.
 
 .. code-block:: bash
 
-   make test
+    nox -s test
+
+This installs your version of ``iminuit`` locally and all the dependencies needed to run the tests, and then runs the tests.
 
-Same and generate a coverage report:
+To generate a coverage report you do:
 
 .. code-block:: bash
 
-    make cov
+    nox -s cov
     <your-web-browser> htmlcov/index.htm
 
 Build the docs:
 
 .. code-block:: bash
 
-   make doc
-   <your-web-browser> doc/_build/html/index.html
-
-Run the notebook tests:
-
-.. code-block:: bash
-
-   make tutorial
+   nox -s doc
+   <your-web-browser> build/html/index.html
 
-Maintainers that prepare a release, should follow the instructions in `doc/README.md`_
+Maintainers that prepare a release, should follow the instructions in `doc/README.md`
 
 To check your ``iminuit`` version number and install location:
 
@@ -101,4 +80,3 @@ To check your ``iminuit`` version number and install location:
 .. _Python virtual environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 .. _Github: https://github.com/scikit-hep/iminuit
 .. _Makefile: https://github.com/scikit-hep/iminuit/blob/main/Makefile
-.. _doc/README.md: https://github.com/scikit-hep/iminuit/blob/main/doc/README.md