From cb409a5af2eccfb6dbcce7ae51c5de49dba979a6 Mon Sep 17 00:00:00 2001 From: Hagen Wierstorf Date: Tue, 20 Aug 2024 11:05:56 +0200 Subject: [PATCH] DOC: use sphinx-apipages plugin (#12) --- .gitignore | 1 + audpsychometric/__init__.py | 17 ---- docs/{api.rst => api-src/audpsychometric.rst} | 87 +++++++++---------- docs/conf.py | 9 +- docs/index.rst | 2 +- docs/requirements.txt | 1 + 6 files changed, 50 insertions(+), 67 deletions(-) rename docs/{api.rst => api-src/audpsychometric.rst} (66%) diff --git a/.gitignore b/.gitignore index 5c2fc08..54ebe8e 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ dist/ .idea/ venv/ coverage.xml +docs/api/ docs/pics/*.svg docs/.ipynb_checkpoints docs/examples/output diff --git a/audpsychometric/__init__.py b/audpsychometric/__init__.py index da18365..e7d5457 100644 --- a/audpsychometric/__init__.py +++ b/audpsychometric/__init__.py @@ -1,20 +1,3 @@ -"""Library to facilitate evaluation and processing of annotated speech. - -The input data format for all functions in this module is the same: -a :class:`pd.DataFrame` is expected. - -This dataframe is assumed to - -- have an index that identifies the unit of observation, - e.g. a psychometric item to be rated -- have a separate column for each rater - -So the entry in the frame at (irow, icol) -identifies the rating of unit irow by rather icol. -Note that these assumptions are not checked -and are under responsibility of the user. - -""" import audpsychometric.core from audpsychometric.core import datasets from audpsychometric.core.datasets import list_datasets diff --git a/docs/api.rst b/docs/api-src/audpsychometric.rst similarity index 66% rename from docs/api.rst rename to docs/api-src/audpsychometric.rst index f4ac5bb..f2b8b39 100644 --- a/docs/api.rst +++ b/docs/api-src/audpsychometric.rst @@ -3,9 +3,33 @@ audpsychometric .. automodule:: audpsychometric +Library to facilitate evaluation and processing of annotated speech. + +The input data format for all functions in this module is the same: +a :class:`pd.DataFrame` is expected. + +This dataframe is assumed to + +- have an index that identifies the unit of observation, + e.g. a psychometric item to be rated +- have a separate column for each rater + +So the entry in the frame at (irow, icol) +identifies the rating of unit irow by rather icol. +Note that these assumptions are not checked +and are under responsibility of the user. + Pychometric Analysis -------------------- +.. autosummary:: + :toctree: + :nosignatures: + + cronbachs_alpha + congeneric_reliability + intra_class_correlation + The module currently contains two reliability coefficients from the family of structural equation model (SEM)-based reliability coefficients. @@ -38,54 +62,31 @@ We do not implement it here, as there are other implementations available, e.g. :func:`audmetric.concordance_cc`. -cronbachs_alpha -^^^^^^^^^^^^^^^ - -.. autofunction:: cronbachs_alpha - -congeneric_reliability -^^^^^^^^^^^^^^^^^^^^^^ - -.. autofunction:: congeneric_reliability - -intra_class_correlation -^^^^^^^^^^^^^^^^^^^^^^^ - -.. autofunction:: intra_class_correlation - Gold Standard Calculation ------------------------- -evaluator_weighted_estimator -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autofunction:: evaluator_weighted_estimator +.. autosummary:: + :toctree: + :nosignatures: -gold_standard_mean -^^^^^^^^^^^^^^^^^^ - -.. autofunction:: gold_standard_mean - -gold_standard_median -^^^^^^^^^^^^^^^^^^^^ - -.. autofunction:: gold_standard_median - -gold_standard_mode -^^^^^^^^^^^^^^^^^^ - -.. autofunction:: gold_standard_mode - -rater_confidence_pearson -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. autofunction:: rater_confidence_pearson + evaluator_weighted_estimator + gold_standard_mean + gold_standard_median + gold_standard_mode + rater_confidence_pearson Demo Datasets ------------- +.. autosummary:: + :toctree: + :nosignatures: + + list_datasets + read_dataset + Currently these datasets are defined: .. jupyter-execute:: @@ -94,16 +95,6 @@ Currently these datasets are defined: df_datasets = datasets.list_datasets() print(df_datasets) -list_datasets -^^^^^^^^^^^^^ - -.. autofunction:: list_datasets - -read_dataset -^^^^^^^^^^^^ - -.. autofunction:: read_dataset - .. _one-dimensional congeneric reliability: https://en.wikipedia.org/wiki/Congeneric_reliability .. _CCC: https://en.wikipedia.org/wiki/Concordance_correlation_coefficient diff --git a/docs/conf.py b/docs/conf.py index b258881..ff58059 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,13 @@ master_doc = "index" extensions = [] source_suffix = ".rst" -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] +exclude_patterns = [ + "api-src", + "build", + "Thumbs.db", + ".DS_Store", + "**.ipynb_checkpoints", +] pygments_style = None extensions = [ "jupyter_sphinx", # executing code blocks @@ -28,6 +34,7 @@ "sphinx_autodoc_typehints", "sphinx_copybutton", # for "copy to clipboard" buttons "sphinxcontrib.bibtex", + "sphinx_apipages", ] diff --git a/docs/index.rst b/docs/index.rst index f3f5d58..b4873c3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,7 +14,7 @@ :caption: API Documentation :hidden: - api + api/audpsychometric genindex bibliography diff --git a/docs/requirements.txt b/docs/requirements.txt index f21d291..f1e898d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,6 +2,7 @@ audeer ipykernel jupyter-sphinx sphinx +sphinx-apipages >=0.1.2 sphinx-audeering-theme >=1.2.1 sphinx-autodoc-typehints sphinx-copybutton