Docs: render autodoc & typehints in the API documentation (#359)

* remove uninformative comment block * update setDependencyFileLocation * update getDependencyFileLocation * update setThreshold * update setDerivativeThreshold * add type hints to get_cpp_feature, numpy as np to shorten fn sign * update getFeatureNames, FeatureNameExists, _get_feature * update getDistance * update setInt/Double/Strsettings * update getFeatureValues * update getMeanFeatureValues * update _get_feature_values_serial * readthedocs.yaml py3.9->py3.10 * use the same requirements_docs.txt in readthedocs,tox,Makefile * Fix docstring error in extract_stim_times_from_neo_data * fix docstring error in load_neo_file * enable autodoc + typehints * make CHANGELOG rst * add changelog to docs * update docs' description text * update epubcopyright date * update CHANGELOG * update PR template * fix trailing whitespace * apply Aurelien's review * handle None values in phaseslope_max
BlueBrain · Jan 17, 2024 · 49a3bab · 49a3bab
1 parent 6b185cb
commit 49a3bab
Show file tree

Hide file tree

Showing 13 changed files with 377 additions and 362 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,6 +1,4 @@
 
-# Pull Request Template
-
 ## Description
 
 Please include a summary of the change.
@@ -9,6 +7,6 @@ To increment major or minor changes add #major or #minor to the PR description.
 
 
 ## Checklist:
-- [ ] Unit tests are added to cover the changes.
-- [ ] The changes are mentioned in the documentation.
-- [ ] CHANGELOG.md is updated (skip if the change is not important for the changelog).
+- [ ] Unit tests are added to cover the changes (skip if not applicable).
+- [ ] The changes are mentioned in the documentation (skip if not applicable).
+- [ ] CHANGELOG file is updated (skip if not applicable).
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.10"
 
 python:
   # Install our python package before building the docs

diff --git a/CHANGELOG.md → CHANGELOG.rst b/CHANGELOG.md → CHANGELOG.rst
@@ -1,36 +1,46 @@
-
-# Changelog
+Changelog
+=========
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
+and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
-## [5.5.4] - 2024-01
+5.5.5 - 2024-01
+----------------
+- Type annotate api.py's functions.
+- Deprecate camel case function names in api.py.
+- Start using same requirements_docs.txt in readthedocs and tox.
+- Enable autodoc and typehints in the API documentation.
+- Fix docstring errors in the io module.
+- Add changelog to the documentation.
 
+[5.5.4] - 2024-01
+-----------------
 - New feature: phaseslope_max
 
-## [5.5.3] - 2024-01
-
+5.5.3 - 2024-01
+----------------
 - Add type stub for cppcore module to make Python recognise the C++ functions' arguments and return values.
 
-## [5.5.0] - 2024-01
-
-### C++ changes
-- AP_end_indices, AP_rise_time, AP_fall_time, AP_rise_rate, AP_fall_rate do not take into account peaks before stim_start anymore
-- New test and test data for spontaneous firing case.
-  The data is provided by github user SzaBoglarka using cell https://modeldb.science/114047
-
-
-## [5.4.0] - 2024-01
-
-### C++ changes
+5.5.0 - 2024-01
+----------------
+C++ changes
+^^^^^^^^^^^
+- AP_end_indices, AP_rise_time, AP_fall_time, AP_rise_rate, AP_fall_rate do not take into account peaks before stim_start anymore.
+- New test and test data for spontaneous firing case. The data is provided by github user SzaBoglarka using cell `https://modeldb.science/114047 <https://modeldb.science/114047>`_.
+
+5.4.0 - 2024-01
+----------------
+C++ changes
+^^^^^^^^^^^
 - New C++ function `getFeatures` replaced `getVec`.
 - `getFeatures` automatically handles failures & distinguishes empty results from failures.
 - Centralized error handling in `getFeatures` shortens the code by removing repetitions.
 - C++ features' access is restricted. Read-only references are marked `const`.
 - Removed wildcard features from C++ API. Use of Python is encouraged for that purpose.
 
-### Python changes
+Python changes
+^^^^^^^^^^^^^^
 - `bpap_attenuation` feature is added to the Python API.
 - `Spikecount`, `Spikecount_stimint`, `burst_number`, `strict_burst_number` and `trace_check` features migrated to Python from C++.
 - `check_ais_initiation` is added to the Python API.
diff --git a/Makefile b/Makefile
@@ -12,7 +12,7 @@ doc_efeatures:
 	ls -al ../../build_efeatures && \
 	pdflatex -output-directory=../../build_efeatures efeature-documentation.tex
 doc: install doc_efeatures
-	pip install sphinx sphinx-autobuild sphinx_rtd_theme
+	pip install -r requirements_docs.txt
 	cd docs; $(MAKE) clean; $(MAKE) html SPHINXOPTS=-W
 doc_upload: doc
 	cd docs/build/html && \

diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -29,7 +29,15 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode',
-              'sphinx.ext.autosummary', 'sphinx.ext.napoleon']
+              'sphinx.ext.autosummary', 'sphinx.ext.napoleon', "sphinx_autodoc_typehints"]
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+autodoc_default_options = {
+    "members": True,
+}
+
+# Autodoc-typehints settings
+always_document_param_types = True
+typehints_use_rtype = True
 
 napoleon_numpy_docstring = True
 
@@ -47,7 +55,7 @@
 
 # General information about the project.
 project = u'eFEL'
-copyright = u'2015-2022, BBP, EPFL'
+copyright = u'2015-2024, BBP, EPFL'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -259,7 +267,7 @@
 epub_title = u'eFEL'
 epub_author = u'BBP, EPFL'
 epub_publisher = u'BBP, EPFL'
-epub_copyright = u'2015-2022, BBP, EPFL'
+epub_copyright = u'2015-2024, BBP, EPFL'
 
 # The language of the text. It defaults to the language option
 # or en if the language is not set.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -14,9 +14,7 @@ calculated. The library will then extract the requested eFeatures and return the
 values to the user.
 
 The core of the library is written in C++, and a Python wrapper is included.
-At the moment we provide a way to automatically compile and install the library
-as a Python module. Soon instructions will be added on how to link C++ code
-directly with the eFEL.
+You can automatically compile and install the library as a Python module.
 
 The source code of the eFEL is located on github:
 `BlueBrain/eFEL <https://github.com/BlueBrain/eFEL>`_
@@ -28,6 +26,7 @@ The source code of the eFEL is located on github:
    examples
    eFeatures
    api
+   changelog
    developers
 
 Indices and tables