[DOC] Update documentation pages and update coverage config (braindat…

…alab#21)
retune-commons · Sep 13, 2024 · ea80d34 · ea80d34
1 parent 8b98daf
commit ea80d34
Show file tree

Hide file tree

Showing 10 changed files with 83 additions and 93 deletions.
diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml
@@ -59,7 +59,7 @@ jobs:
       - run: pip install -e .
       - run: python -c "import pybispectra; import mne; print(f'PyBispectra {pybispectra.__version__}\n'); mne.sys_info()"
       - name: Run pytest
-        run: python -m coverage run --source=pybispectra -m pytest -v tests && coverage report -m
+        run: python -m coverage run && coverage report
 
   test_conda:
     timeout-minutes: 90
@@ -89,4 +89,4 @@ jobs:
       - name: Display versions and environment information
         run: python -c "import pybispectra; import mne; print(f'PyBispectra {pybispectra.__version__}\n'); mne.sys_info()"
       - name: Run pytest
-        run: python -m coverage run --source=pybispectra -m pytest -v tests && coverage report -m
+        run: python -m coverage run && coverage report
diff --git a/docs/make.bat b/docs/make.bat
@@ -8,6 +8,8 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
+set AUTOEXDIR=%SOURCEDIR%\auto_examples
+set GENDIR=%SOURCEDIR%\generated
 set BUILDDIR=build
 
 %SPHINXBUILD% >NUL 2>NUL
@@ -24,12 +26,20 @@ if errorlevel 9009 (
 )
 
 if "%1" == "" goto help
+if "%1" == "clean" goto clean
 
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:clean
+echo Removing everything under '%AUTOEXDIR%' and '%GENDIR%'...
+del /S /Q %AUTOEXDIR%\* >nul 2>&1
+del /S /Q %GENDIR%\* >nul 2>&1
+%SPHINXBUILD% -M clean %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
 popd
diff --git a/docs/source/_static/requirements.txt b/docs/source/_static/requirements.txt
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -1,6 +1,8 @@
 API
 ===
 
+Here are the API references for the classes and functions of PyBispectra.
+
 .. container:: d-none
 
     :py:mod:`pybispectra`:

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -32,6 +32,7 @@
     "numpydoc",
     "sphinxcontrib.bibtex",
     "sphinx_gallery.gen_gallery",
+    "sphinx_copybutton",
 ]
 
 source_suffix = [".rst", ".md"]

diff --git a/docs/source/development.rst b/docs/source/development.rst
@@ -10,52 +10,53 @@ View the changelog for each PyBispectra version here: `version changelog
 Installing PyBispectra in editable mode
 ---------------------------------------
 
-If you want to make changes to PyBispectra, you may wish to install it in
-editable mode. To do so, first clone the `GitHub repository
-<https://github.com/braindatalab/PyBispectra/tree/main>`_ to your desired
-location. Once cloned, navigate to this location and install the package
-alongside its development requirements using pip:
+If you want to make changes to PyBispectra, you may wish to install it in editable mode.
+To do so, first clone the `GitHub repository
+<https://github.com/braindatalab/PyBispectra/tree/main>`_ to your desired location. Once
+cloned, navigate to this location and install the package alongside its development
+requirements using pip:
 
-.. code-block:: console
+.. code-block::
     
-    $ pip install -e .
-    $ pip install pybispectra[dev]
+    pip install -e .
+    pip install .[dev]
 
 
 Contributing to PyBispectra
 ---------------------------
 
-If you encounter any issues with the package or wish to suggest improvements,
-please submit a report on the `issues page
+If you encounter any issues with the package or wish to suggest improvements, please
+submit a report on the `issues page
 <https://github.com/braindatalab/PyBispectra/issues>`_.
 
-If you have made any changes which you would like to see officially added to
-the package, consider submitting a `pull request
-<https://github.com/braindatalab/PyBispectra/pulls>`_. When submitting a pull
-request, please check that the existing test suite passes, and if you add new
-features, please make sure that these are covered in the unit tests. The tests
-can be run by calling `coverage <https://coverage.readthedocs.io/en/>`_ with
-`pytest <https://docs.pytest.org/en/>`_ in the base directory:
+If you have made any changes which you would like to see officially added to the
+package, consider submitting a `pull request
+<https://github.com/braindatalab/PyBispectra/pulls>`_. A unit test suite is included.
+Tests must be added for any new features, and adaptations to the existing tests must be
+made where necessary. Checks for these tests are run when a pull request is submitted,
+however these tests can also be run locally by calling `coverage
+<https://coverage.readthedocs.io/en/>`_ with `pytest <https://docs.pytest.org/en/>`_ in
+the base directory:
 
-.. code-block:: console
+.. code-block::
     
-    $ coverage run --source=pybispectra -m pytest -v tests && coverage report -m
+    coverage run && coverage report
 
-Please also check that the documentation can be built following any changes,
-which can be done using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ in
-the ``/docs`` directory:
+Please also check that the documentation can be built following any changes. The
+documentation is built when a pull request is submitted, however the documentation can
+also be built locally using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ in the
+``/docs`` directory (outputs are in the ``/docs/build/html`` directory):
 
-.. code-block:: console
+.. code-block::
     
-    $ make html
+    make html
 
-Finally, features of the code such as compliance with established styles and
-spelling errors in the documentation are also checked. Please ensure that the
-code is formatted using `Black <https://black.readthedocs.io/en/stable/>`_, and
-check that there are no egregious errors from the following commands:
+Finally, features of the code such as compliance with established styles and spelling
+errors in the documentation are also checked. These checks are run when a pull request
+is submitted, however they can also be run locally using `pre-commit
+<https://pre-commit.com/>`_. To have these checks run automatically whenever you commit
+changes, install ``pre-commit`` with the following command in the base directory:
 
-.. code-block:: console
+.. code-block::
     
-    $ flake8
-    $ pydocstyle
-    $ codespell
+    pre-commit install
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -1,7 +1,7 @@
 Examples
 ========
 
-Find out how to get started with the package using the provided examples:
+Find out how to get started with PyBispectra using the provided examples.
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,20 +11,20 @@
    :alt: PyBispectra
 
 |br|
-A Python signal processing package for computing spectral- and time-domain
-interactions using the bispectrum.
+A Python signal processing package for computing spectral- and time-domain interactions
+using the bispectrum.
 
-This package provides the tools for computing phase-amplitude coupling, time
-delay estimation, and waveshape features using the bispectrum and bicoherence.
-Additional tools for computing amplitude-amplitude coupling, phase-phase
-coupling, and spatio-spectral filters are also provided.
+This package provides the tools for computing phase-amplitude coupling, time delay
+estimation, and waveshape features using the bispectrum and bicoherence. Additional
+tools for computing amplitude-amplitude coupling, phase-phase coupling, and
+spatio-spectral filters are also provided.
 
 Parallel processing and `Numba <https://numba.pydata.org/>`_ optimisation are
-implemented to reduce computation times. There is a minor reliance on the
-`MNE <https://mne.tools/stable/index.html>`_ signal processing toolbox.
+implemented to reduce computation times.
 
 If you use this toolbox in your work, please include the following citation:|br|
-Binns, T. S., Pellegrini, F., Jurhar, T., & Haufe, S. (2023). PyBispectra. DOI: `10.5281/zenodo.8377820 <https://doi.org/10.5281/zenodo.8377820>`_
+Binns, T. S., Pellegrini, F., Jurhar, T., & Haufe, S. (2023). PyBispectra. DOI:
+`10.5281/zenodo.8377820 <https://doi.org/10.5281/zenodo.8377820>`_
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -1,22 +1,22 @@
 Installation
 ============
 
-To install PyBispectra, activate the desired environment in which you want the
-package, then install it using pip:
+To install PyBispectra, activate the desired environment in which you want the package,
+then install it using pip:
 
-.. code-block:: console
+.. code-block::
     
-    $ pip install pybispectra
+    pip install pybispectra
 
-PyBispectra requires Python >= 3.10. Other requirements are listed
-`here <_static/requirements.txt>`_.
+PyBispectra requires Python >= 3.10.
 
-If you need to create an environment in which to install PyBispectra, you can
-do so using `conda <https://docs.conda.io/en/latest/>`_, after which you can
-install the package:
+If you need to create an environment in which to install PyBispectra, you can do so
+using `conda <https://docs.conda.io/en/latest/>`_, after which you can install the
+package:
 
-.. code-block:: console
+.. code-block::
 
-    $ conda create -n pybispectra_env
-    $ conda activate pybispectra_env
-    $ pip install pybispectra
+    conda create -n pybispectra_env
+    conda activate pybispectra_env
+    conda install -c conda-forge pip
+    pip install pybispectra
diff --git a/pyproject.toml b/pyproject.toml
@@ -3,34 +3,21 @@ build-backend = "hatchling.build"
 requires = ["hatchling"]
 
 [project]
-authors = [
-  {email = "[email protected]", name = "Thomas Samuel Binns"},
-]
+authors = [{email = "[email protected]", name = "Thomas Samuel Binns"}]
 classifiers = [
   "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
 ]
-dependencies = [
-  "joblib",
-  "matplotlib",
-  "mne>1.6",
-  "numba",
-  "numpy",
-  "scipy",
-]
+dependencies = ["joblib", "matplotlib", "mne>1.6", "numba", "numpy", "scipy"]
 description = "A Python signal processing package for computing spectral-domain and time-domain interactions using the bispectrum."
 name = "pybispectra"
 readme = "README.md"
 requires-python = ">=3.10"
 version = "1.2.0dev"
 
 [project.optional-dependencies]
-dev = [
-  "pybispectra[doc]",
-  "pybispectra[lint]",
-  "pybispectra[test]",
-]
+dev = ["pybispectra[doc]", "pybispectra[lint]", "pybispectra[test]"]
 doc = [
   "ipykernel",
   "ipython",
@@ -39,6 +26,7 @@ doc = [
   "numpydoc",
   "pydata-sphinx-theme",
   "sphinx",
+  "sphinx-copybutton",
   "sphinx-gallery",
   "sphinxcontrib-bibtex",
 ]
@@ -53,10 +41,7 @@ lint = [
   "toml-sort",
   "yamllint",
 ]
-test = [
-  "coverage",
-  "pytest",
-]
+test = ["coverage", "pytest"]
 
 [project.urls]
 "Bug Tracker" = "https://github.com/braindatalab/PyBispectra/issues"
@@ -66,12 +51,13 @@ test = [
 ignore-words-list = "trough"
 skip = "./docs/build,./docs/source/auto_examples,./docs/source/refs.bib"
 
+[tool.coverage.report]
+show_missing = true
+
 [tool.coverage.run]
-omit = [
-  "__init__.py",
-  "src/pybispectra/utils/_docs.py",
-  "tests/*",
-]
+command_line = "-m pytest -v tests"
+omit = ["__init__.py", "src/pybispectra/utils/_docs.py", "tests/*"]
+source = ["pybispectra"]
 
 [tool.isort]
 profile = "black"
@@ -133,10 +119,7 @@ ignore_roles = [
 report_level = "WARNING"
 
 [tool.ruff]
-extend-exclude = [
-  "docs",
-  "examples/compute_*.py",
-]
+extend-exclude = ["docs", "examples/compute_*.py"]
 line-length = 88
 
 [tool.ruff.lint.per-file-ignores]