From 3127b86e8fb463977b559f2f452fc9c57bcafccb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20N=C3=B6the?= Date: Mon, 28 Sep 2020 12:02:38 +0200 Subject: [PATCH 1/4] Add section about unit tests and coverage to the contributing docs --- docs/contribute.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/contribute.rst b/docs/contribute.rst index fd10dc3d0..b889ac8fc 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -48,6 +48,38 @@ We use `Travis CI `__ to run the unit tests and documentation building automatically for every pull request. Passing unit tests and coverage of the changed code are required for all pull requests. + +Running the tests and looking at coverage +----------------------------------------- + +For more immediate feedback, you should run the tests locally before pushing, +as builds on travis take quite long. + +To run the tests locally, make sure you have the `tests` extras installed and then +run + +.. code:: bash + + $ pytest -v + + +To also inspect the coverage, run + +.. code:: bash + + $ pytest --cov=pyirf --cov-report=html -v + +This will create a coverage report in html form in the ``htmlcov`` directory, +which you can serve locally using + +.. code:: bash + + $ python -m http.server -d htmlcov + +After this, you can view the report in your browser by visiting the url printed +to the terminal. + + Further details --------------- From 714ab475707714ccc026e6bb650196fb1cd4c52e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20N=C3=B6the?= Date: Mon, 28 Sep 2020 12:06:11 +0200 Subject: [PATCH 2/4] Add section about building the docs locally --- docs/contribute.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/contribute.rst b/docs/contribute.rst index b889ac8fc..67b066af0 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -79,6 +79,40 @@ which you can serve locally using After this, you can view the report in your browser by visiting the url printed to the terminal. +Make sure the docs are built without warnings from sphinx, as these +will be treated as errors in the build in the CI system as they most often +result in broken styling. + +To look at the docs, use + +.. code:: bash + + $ python -m http.server _build/html + +and visit the printed URL in your browser. + + +Building the documentation +-------------------------- + +This documentation uses sphinx and restructured text. +For an Introduction, see the `Sphinx documentation `_. + +To build the docs locally, enter the ``docs`` directory and call: + +.. code:: bash + + make html + +Some changes require a full remake of the documentation, for that call + +.. code:: bash + + make clean html + +If you created or deleted file or submodule, you also need to remove the +``api`` directory, it will be regenerated automatically. + Further details --------------- From 7ea6e4430831830a6209f3055b0c0e1c5c64a535 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20N=C3=B6the?= Date: Mon, 28 Sep 2020 12:09:56 +0200 Subject: [PATCH 3/4] Move paragraphs to the correct section --- docs/contribute.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/contribute.rst b/docs/contribute.rst index 67b066af0..1a1b3df85 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -79,18 +79,6 @@ which you can serve locally using After this, you can view the report in your browser by visiting the url printed to the terminal. -Make sure the docs are built without warnings from sphinx, as these -will be treated as errors in the build in the CI system as they most often -result in broken styling. - -To look at the docs, use - -.. code:: bash - - $ python -m http.server _build/html - -and visit the printed URL in your browser. - Building the documentation -------------------------- @@ -113,6 +101,19 @@ Some changes require a full remake of the documentation, for that call If you created or deleted file or submodule, you also need to remove the ``api`` directory, it will be regenerated automatically. +Make sure the docs are built without warnings from sphinx, as these +will be treated as errors in the build in the CI system as they most often +result in broken styling. + +To look at the docs, use + +.. code:: bash + + $ python -m http.server _build/html + +and visit the printed URL in your browser. + + Further details --------------- From aa488f455a59005b67f7054e7646ee4be1507897 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20N=C3=B6the?= Date: Mon, 28 Sep 2020 14:28:37 +0200 Subject: [PATCH 4/4] Fix link to notebook in contributing --- docs/contribute.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute.rst b/docs/contribute.rst index 1a1b3df85..ed689df7b 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -132,4 +132,4 @@ Please also have a look at the Benchmarks ---------- -- `Comparison with EventDisplay <../notebooks/comparison_with_EventDisplay.ipynb>`__ | *comparison_with_EventDisplay.ipynb* +- :doc:`notebooks/comparison_with_EventDisplay`