Merge pull request #97 from umcu/add-docstrings

Add docstrings

.gitignore

@@ -77,6 +77,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/api/clinlp/
 
 # PyBuilder
 target/

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 :exclamation: = Breaking change
 
+## (unreleased)
+
+### Added
+* Docstrings on all modules, classes, methods and functions
+
+### Changed
+* In `InformationExtractionDataset`, renamed `span_counts`, `label_counts` and `qualifier_counts` to `span_freqs`, `label_freqs` and `qualifier_freqs` respectively.
+* The `clinlp_component` utility now returns the class itself, rather than a helper function for making it
+* Changed order of `direction` and `qualifier` arguments of `ContextRule`
+
 ## 0.8.0 (2024-06-03)
 
 ### Changed

Makefile

@@ -6,4 +6,8 @@ clean:
 	rm -rf .pytest_cache
 	rm -rf dist
 
-.PHONY: lint clean
+build-docs:
+	sphinx-apidoc --module-first --force --templatedir=docs/_templates -o docs/source/api/clinlp src
+	sphinx-build docs/source docs/_build/html -c docs/
+
+.PHONY: lint clean build-docs

README.md

@@ -1,4 +1,5 @@
 [![test](https://github.com/umcu/clinlp/actions/workflows/test.yml/badge.svg)](https://github.com/umcu/clinlp/actions/workflows/test.yml)
+[![docs](https://readthedocs.org/projects/clinlp/badge/?version=latest)](https://clinlp.readthedocs.io/en/latest/?badge=latest)
 [![pypi version](https://img.shields.io/pypi/v/clinlp?color=blue)](https://pypi.org/project/clinlp/)
 [![pypi python versions](https://img.shields.io/pypi/pyversions/clinlp)](https://pypi.org/project/clinlp/)
 [![license](https://img.shields.io/github/license/umcu/clinlp?color=blue)](https://github.com/umcu/clinlp/blob/main/LICENSE)
@@ -65,7 +66,7 @@ text = (
 doc = nlp(text)
 ```
 
-Find information in the doc object:
+Find information in the `Doc` object:
 
 ```python
 from spacy import displacy
@@ -248,7 +249,7 @@ concepts = {
 
 In this case `prematuur` will be matched, but not in the context of `prematuur ademhalingspatroon` (which may indicate prematurity, but is not a definitive diagnosis).
 
-#### Spacy patterns
+#### spaCy patterns
 
 Finally, if you need more control than literal phrases and terms as explained above, the entity matcher also accepts [spaCy patterns](https://spacy.io/usage/rule-based-matching#adding-patterns). These patterns do not respect any other configurations (like attribute, fuzzy, proximity, etc.):
 

docs/.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+build:
+  os: "ubuntu-lts-latest"
+  tools:
+    python: "3.12"
+  commands:
+    - pip install poetry
+    - poetry config virtualenvs.create false
+    - poetry install --without dev --with docs
+    - make build-docs
+    - cp -r docs/_build _readthedocs

docs/_templates/modules.rst_t

@@ -0,0 +1,8 @@
+{%- if show_headings %}
+{{- [basename, "module"] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}

docs/_templates/package.rst_t

@@ -0,0 +1,45 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}

docs/_templates/toc.rst_t

@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}

docs/conf.py

@@ -0,0 +1,51 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import datetime
+import sys
+from pathlib import Path
+
+import toml
+
+sys.path.append(Path(__file__).parent)
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+toml_config = toml.load("../pyproject.toml")
+
+project = toml_config["tool"]["poetry"]["name"]
+release = toml_config["tool"]["poetry"]["version"]
+
+copyright = f"{datetime.datetime.now().year}, clinlp"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "myst_parser"]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+autodoc_default_options = {
+    "member-order": "bysource",
+    "special-members": "__call__",
+    "ignore-module-all": True,
+}
+
+myst_heading_anchors = 3
+
+napoleon_include_init_with_doc = True
+napoleon_use_rtype = False
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"

docs/qualifier_definitions.md

@@ -1,3 +1,3 @@
 # Qualifier operational definitions
 
-It's useful to have some operational definitions of a qualifier/context, i.e. what we mean exactly when we talk about negations, hypothetical situations, etc. For now the framework we use can be found here: [qualifiers.docx](qualifiers.docx). This information will be incorporated in a separate documentation page in the near future. 
+It's useful to have some operational definitions of a qualifier/context, i.e. what we mean exactly when we talk about negations, hypothetical situations, etc. For now the framework we use can be found here: [qualifiers.docx](qualifiers.docx). This information will be incorporated in a separate documentation page in the near future.

docs/source/api/api.rst

@@ -0,0 +1,9 @@
+API
+===
+
+This page contains the automatically generated ``API`` for ``clinlp``.
+
+.. toctree::
+   :maxdepth: 4
+
+   clinlp/clinlp

docs/source/index.md

@@ -0,0 +1,19 @@
+# clinlp documentation
+
+Welcome to the documentation pages for `clinlp`.
+
+```{toctree}
+:caption: Search & index
+:hidden:
+
+General index <genindex>
+Module index <modindex>
+
+```
+
+```{toctree}
+:caption: Development
+:hidden:
+
+API <api/api>
+```