DOC: Refactor documentation for faster builds

- Switch from Jupyter Book to Sphinx
- Use sphinx-book-theme as docs theme
- Use myst-parser for Markdown support
- Add commands for incremental development
- Generate API docs statically with sphinx-apidoc

Author: ghisvail

.readthedocs.yaml

@@ -6,10 +6,6 @@ python:
       path: .
       extra_requirements:
         - docs
-        - metrics-ner
-        - nlstruct
-        - srt-io-converter
-        - webrtc-voice-detector
 
 build:
   os: ubuntu-22.04
@@ -18,6 +14,3 @@ build:
   apt_packages:
     - graphviz
     - libsndfile1
-  jobs:
-    pre_build:
-      - jupyter-book config sphinx docs/

docs/_config.yml

@@ -0,0 +1,2 @@
+:::{include} ../CHANGELOG.md
+:::

docs/_static/medkit-icon.png

@@ -0,0 +1,48 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "medkit"
+author = "HeKA Research Team"
+project_copyright = f"2022-2024, {author}"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "autoapi.extension",
+    "myst_parser",
+    "numpydoc",
+    "sphinxcontrib.mermaid",
+]
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- autoapi configuration ---------------------------------------------------
+# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
+
+autoapi_dirs = ["../medkit"]
+autoapi_root = "api/_generated"
+
+# -- myst_parser configuration -----------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/configuration.html
+
+myst_enable_extensions = ["attrs_inline", "colon_fence"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "path_to_docs": "docs",
+    "repository_url": "https://github.com/medkit-lib/medkit",
+    "repository_branch": "main",
+}
+html_title = "medkit documentation"
+html_logo = "_static/medkit-logo.png"
+html_favicon = "_static/medkit-icon.png"
+html_static_path = ["_static"]

docs/img/medkit_logo.png docs/_static/medkit-logo.png

@@ -1,20 +1,88 @@
-# medkit - documentation
+# medkit
 
-***medkit*** is a Python library for facilitating the **extraction of features** from various modalities of patient data: text, audio for now - relational, image, genetic, and others soon. To this end, medkit offers to compose pipelines with modules, developed by us, yourself or others.
+`medkit` is a Python library which facilitates **extraction of features**
+from various modalities of patient data, including text and audio for now
+-- relational, image, genetic, and others will follow soon.
 
-We pay particular attention to enable the implementation of **non-destructive pipelines** (no loss of information when passing from a module to another) and a flexible tracing of **data provenance**.
+To this end, medkit enables composition of pipelines with multiple modules,
+developed by us, yourself or others.
 
-***medkit*** aims at accelerating the development of a learning health system, with a strong open-source and community orientation.
+`medkit` places a strong emphasis on **non-destructive operations**,
+i.e. no loss of information when passing data from a module to another,
+and a flexible tracing of **data provenance**.
+
+`medkit` aims at accelerating the development of a learning health system,
+with a strong dedication to open-source and community development.
 
 :::{warning}
-*medkit* core library is still under development and testing.
-Some interfaces may change in the future.
+The `medkit` core library is still under heavy development and testing.
+Some public interfaces may change in the future.
+Please check the **BREAKING CHANGES** section of the project's changelog for details.
+:::
+
+:::{toctree}
+---
+caption: User Guide
+hidden:
+titlesonly:
+---
+user_guide/install
+user_guide/first_steps
+user_guide/pipeline
+user_guide/provenance
+user_guide/module
+:::
 
-This library with its documentation is shared for following reasons:
-* helping people with some guidelines for using first medkit versions,
-* helping core development team to get user feedback for improving the *medkit* library.
+:::{toctree}
+---
+caption: Examples
+hidden:
+titlesonly:
+---
+examples/spans
+examples/cleaning_text
+examples/text_segmentation/index
+examples/text_segmentation/section
+examples/text_segmentation/syntagma
+examples/text_segmentation/document
+examples/brat_io
+examples/spacy/index
+examples/spacy/spacy_io
+examples/spacy/spacy_pipeline
+examples/custom_text_operation
+examples/edsnlp
+examples/iamsystem
+examples/finetuning_hf_model
+examples/detecting_text_duplicates
+examples/audio_transcription
+examples/audio_dataset_metrics
+examples/ontotox
 :::
 
+:::{toctree}
+---
+caption: Tutorial
+hidden:
+titlesonly:
+---
+tutorial/context_detection
+tutorial/entity_matching
+:::
 
-```{tableofcontents}
-```
+:::{toctree}
+---
+caption: Reference
+hidden:
+titlesonly:
+---
+api/_generated/index
+api/audio
+api/core
+api/core_audio
+api/core_text
+api/io
+api/text
+api/training
+api/tools
+changelog
+:::