Fix docs reference (#208)

* Fix docs reference

* typo

* Black formatted dts_accessor.py

* Skip errors in coverage of example notebooks

* Fix doc headers to end with colons

* Improved docs

Parallel tests are configured by using xdist. worksteal resulted in issues and xdist was already set

* Use isinstance() rather than type() for a typecheck.

* Formatting

.gitignore

@@ -57,7 +57,7 @@ output/*/index.html
 
 # Sphinx
 docs/_build
-**/generated/**/*
+**/generated
 
 .DS_Store
 *~
@@ -74,3 +74,4 @@ docs/_build
 *.bak
 .vscode/settings.json
 *.code-workspace
+xunit-result.xml

README.rst

@@ -95,7 +95,7 @@ Documentation
 
 * A full calibration procedure for single-ended setups is presented in notebook `07Calibrate_single_ended.ipynb <https://github.com/dtscalibration/python-dts-calibration/blob/main/docs/notebooks/07Calibrate_single_ended.ipynb>`_ and for double-ended setups in `08Calibrate_double_ended.ipynb <https://github.com/dtscalibration/python-dts-calibration/blob/main/docs/notebooks/08Calibrate_double_ended.ipynb>`_.
 * Documentation at https://python-dts-calibration.readthedocs.io/ .
-* Example notebooks that work within the browser can be viewed `here <https://python-dts-calibration.readthedocs.io/en/latest/learn_by_examples.html>`_.
+* Example notebooks (`./docs/notebooks`) that work within the browser can be viewed `here <https://mybinder.org/v2/gh/dtscalibration/python-dts-calibration/main?labpath=docs%2Fnotebooks>`_.
 
 How to cite
 ===========

docs/reference/index.rst

@@ -4,48 +4,70 @@ Reference
 Load the data
 -------------
 
-See example notebooks 01, A2, A3, and A4.
+See example notebooks 01, A2, A3, and A4. Import directly from `dtscalibration`.
 
-.. automodule:: dtscalibration.io
-   :members: dtscalibration.read_apsensing_files
-   :nosignatures:
+.. currentmodule:: dtscalibration
+.. autosummary::
+    :toctree: ./generated
+    :nosignatures:
+
+    read_apsensing_files
+    read_sensornet_files
+    read_sensortran_files
+    read_silixa_files
 
 Compute the variance in the Stokes measurements
 -----------------------------------------------
 
-See example notebooks 04 and have a look at the docstring of the dtscalibration.variance_stokes funcitons.
+See example notebooks 04. Import from `dtscalibration.variance_stokes`.
+
+.. currentmodule:: dtscalibration.variance_stokes
+.. autosummary::
+    :toctree: ./generated
+    :nosignatures:
 
-.. automodule:: dtscalibration.variance_stokes
-   :members:
-   :nosignatures:
+    variance_stokes_constant
+    variance_stokes_linear
+    variance_stokes_exponential
 
 
 The DTS Accessor
 ----------------
 
-See example natebooks 07, 08, and 17.
+These methods are available as an `xarray.Dataset` accessor. Add 
+`from dtscalibration.dts_accessor import DtsAccessor` to your import 
+statements. See example natebooks 07, 08, and 17.
 
-.. currentmodule:: xarray
+.. currentmodule:: xarray.Dataset
 .. autosummary::
     :toctree: generated/
     :template: autosummary/accessor_method.rst
     :nosignatures:
 
-    Dataset.dts.sections
-    Dataset.dts.calibrate_single_ended
-    Dataset.dts.calibrate_double_ended
-    Dataset.dts.monte_carlo_single_ended
-    Dataset.dts.monte_carlo_double_ended
-    Dataset.dts.average_monte_carlo_single_ended
-    Dataset.dts.average_monte_carlo_double_ended
-    Dataset.dts.get_default_encoding
-    Dataset.dts.get_timeseries_keys
-    Dataset.dts.matching_sections
-    Dataset.dts.ufunc_per_section
+    dts.sections
+    dts.calibrate_single_ended
+    dts.calibrate_double_ended
+    dts.monte_carlo_single_ended
+    dts.monte_carlo_double_ended
+    dts.average_monte_carlo_single_ended
+    dts.average_monte_carlo_double_ended
+    dts.get_default_encoding
+    dts.get_timeseries_keys
+    dts.matching_sections
+    dts.ufunc_per_section
 
 Plot the results
 ----------------
 
-.. automodule:: dtscalibration.plot
-   :members:
-   :nosignatures:
+Import from `dtscalibration.plot`.
+
+.. currentmodule:: dtscalibration.plot
+.. autosummary::
+    :toctree: ./generated
+    :nosignatures:
+
+    plot_residuals_reference_sections
+    plot_residuals_reference_sections_single
+    plot_accuracy
+    sigma_report
+    plot_location_residuals_double_ended

pyproject.toml

@@ -106,16 +106,16 @@ features = ["dev"]
 
 [tool.hatch.envs.default.scripts]
 lint = [
-  "ruff check .",
-  "black --check .",
-  "isort --check-only --diff .",
+  "ruff check src/ tests/ examples/",
+  "black --check src/ tests/ examples/",
+  "isort --check-only --diff src/ tests/ examples/",
   "mypy src/",
 ]
-format = ["black .", "isort .", "lint",]
-test = ["pytest -n auto --dist worksteal ./src/ ./tests/",]
-fast-test = ["pytest -n auto --dist worksteal ./tests/ -m \"not slow\"",]
+format = ["isort src/ tests/ examples/", "ruff check src/ tests/ examples/ --fix", "black src/ tests/ examples/", "lint",]
+test = ["pytest ./src/ ./tests/",]
+fast-test = ["pytest ./tests/ -m \"not slow\"",]
 coverage = [
-  "pytest --cov --cov-report term --cov-report xml --junitxml=xunit-result.xml tests/",
+  "pytest --cov --cov-report term --cov-report xml --cov-branch --junitxml=xunit-result.xml tests/",
 ]
 
 [tool.hatch.envs.docs]
@@ -152,20 +152,23 @@ select = [  # It would be nice to have the commented out checks working.
   "UP",  # pyupgrade (upgrade syntax to current syntax)
   "PLE",  # Pylint error https://github.com/charliermarsh/ruff#error-ple
   # "PLR",  # Pylint refactor (e.g. too-many-arguments)
-  # "PLW",  # Pylint warning (useless-else-on-loop)
+  "PLW",  # Pylint warning (useless-else-on-loop)
+  # "I",  # isort
+  "SIM",  # flake8-simplify
+
 ]
 extend-select = [
-  # "D401",  # First line should be in imperative mood
-  # "D400",  # First line should end in a period.
-  # "D404",  # First word of the docstring should not be "This"
+  "D401",  # First line should be in imperative mood
+  "D400",  # First line should end in a period.
+  "D404",  # First word of the docstring should not be "This"
   "TID252",  # No relative imports (not pep8 compliant)
 ]
 ignore = [
   "PLR2004",  # magic value used in comparson
   "E501",  # Line too long (want to have fixed
 ]
 # Allow autofix for all enabled rules (when `--fix`) is provided.
-fixable = ["E", "F", "UP", "PLE"]
+fixable = ["E", "F", "UP", "PLE", "D"]
 unfixable = []
 line-length = 88
 exclude = ["docs", "build"]
@@ -183,6 +186,9 @@ convention = "google"
 [tool.ruff.mccabe]
 max-complexity = 10
 
+[tool.ruff.lint.isort]
+force-single-line = true
+
 [tool.isort]
 py_version=39
 force_single_line = true