docs: use mkdocs

.gitignore

@@ -155,3 +155,5 @@ dhlab/_version.py
 # vscode settings
 .vscode
 poetry.lock
+docs/new_conf.py
+docs/orig_conf.py

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
     # You can also specify other tool versions:
     # nodejs: "16"
     # rust: "1.55"

docs/api.md

@@ -0,0 +1,16 @@
+# ::: dhlab.api
+    options:
+      show_root_heading: true
+
+## ::: dhlab.api.dhlab_api
+    options:
+      show_root_heading: true
+
+## ::: dhlab.api.nb_ngram_api
+    options:
+      show_root_heading: true
+
+## ::: dhlab.api.nb_search_api
+    options:
+      show_root_heading: true
+

docs/images.md

@@ -0,0 +1,13 @@
+# ::: dhlab.images
+    options:
+      show_root_heading: true
+
+
+## ::: dhlab.images.nbpictures
+    options:
+      show_root_heading: true
+
+
+## ::: dhlab.nbpictures
+    options:
+      show_root_heading: true

docs/index.md

@@ -0,0 +1,26 @@
+
+[![DH-LAB logo](_images/DHlab_logo_web_en_black.png)](https://www.nb.no/dh-lab/)
+
+# Welcome to the dhlab reference documentation
+
+This site documents the [code reference](./reference.md) for the [dhlab python library](https://pypi.org/project/dhlab/) functionalities.
+It is built directly from docstrings in our code library, and so the functionality documented here will reflect the [code base on GitHub](https://github.com/NationalLibraryOfNorway/DHLAB).
+
+Head to our [official homepage](https://www.nb.no/dh-lab/) for tutorials, how-to-guides, interactive web apps, and more information about the DH-lab group.
+
+## Project overview
+
+::: dhlab
+
+## Installation
+
+Ensure that you already have  [Python >= 3.9](https://www.python.org/downloads/) installed.
+
+<!-- start installation -->
+
+Install the latest version of the [`dhlab`](https://pypi.org/project/dhlab/) python package in your (Unix) terminal with pip:
+
+```shell
+pip install -U dhlab
+```
+<!-- end installation -->

docs/metadata.md

@@ -0,0 +1,11 @@
+# ::: dhlab.metadata
+    options:
+      show_root_heading: true
+
+## ::: dhlab.metadata.natbib
+    options:
+      show_root_heading: true
+
+## ::: dhlab.metadata.metadata
+    options:
+      show_root_heading: true

docs/ngram.md

@@ -0,0 +1,11 @@
+# :::dhlab.ngram
+    options:
+      show_root_heading: true
+
+## ::: dhlab.ngram.ngram
+    options:
+      show_root_heading: true
+
+## ::: dhlab.ngram.nb_ngram
+    options:
+      show_root_heading: true

docs/reference.md

@@ -0,0 +1,34 @@
+This pages gives an overview of objects available at the top level of the package,
+that can be imported directly from `dhlab.*`, for example: `from dhlab import Corpus`
+
+
+### Classes and functions
+
+!!! info inline end
+
+    We recommend importing these objects directly from dhlab, e.g.:
+
+        from dhlab import Corpus
+
+    The internal subpackages and module structure may change.
+    If you access the top level objects via full module paths,
+    you may need to refactor your imports with future releases of `dhlab`.
+
+- [`Corpus`][dhlab.text.corpus.Corpus]
+- [`Ngram`][dhlab.ngram.ngram.Ngram]
+- [`Chunks`][dhlab.text.chunking.Chunks]
+- [`Collocations`][dhlab.text.collocations.Collocations]
+- [`Concordance`][dhlab.text.concordance.Concordance]
+- [`Frequencies`][dhlab.text.frequencies.Frequencies]
+- [`WildcardWordSearch`][dhlab.text.wildcard.WildcardWordSearch]
+- [`metadata_from_urn`][dhlab.metadata.natbib.metadata_from_urn]
+- [`metadata_query`][dhlab.metadata.natbib.metadata_query]
+- [`totals`][dhlab.api.dhlab_api.totals]
+
+### Subpackages
+
+- [`api`][dhlab.api]
+- [`images`][dhlab.images]: Retrieve and analyze image data.
+- [`metadata`][dhlab.metadata]: Extract metadata on objects from the digital archive.
+- [`ngram`][dhlab.ngram]: Retrieve n-gram data.
+- [`text`][dhlab.text]: Retrieve and analyze text data.

docs/requirements.txt

@@ -0,0 +1,8 @@
+mkdocs==1.5.2
+mkdocs-autorefs==0.5.0
+mkdocs-material==9.1.21
+mkdocs-material-extensions==1.1.1
+mkdocstrings==0.22.0
+mkdocstrings-python==1.3.0
+mkdocs-section-index==0.3.5
+mkdocs-autorefs==0.5.0

docs/text.md

@@ -0,0 +1,35 @@
+# ::: dhlab.text
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.chunking
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.collocations
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.concordance
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.corpus
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.dispersion
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.frequencies
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.utils
+    options:
+      show_root_heading: true
+
+## ::: dhlab.text.wildcard
+    options:
+      show_root_heading: true

mkdocs.yml

@@ -0,0 +1,67 @@
+site_name: dhlab documentation
+
+
+theme:
+  name: "material"
+  logo: _images/NB-symbol-farge.png
+  favicon: _images/nb_symbol_farge_z5B_icon.ico
+  palette:
+    primary: "white"
+    accent: "red"
+  features:
+    - content.code.copy
+    - navigation.footer
+    - navigation.path
+
+repo_url: https://github.com/NationalLibraryOfNorway/DHLAB
+repo_name: NationalLibraryOfNorway/DHLAB
+
+extra:
+  social:
+    - icon: material/home
+      link: https://www.nb.no/
+      name: National Library of Norway
+    - icon: material/book-search
+      link: https://www.nb.no/search/
+      name: Online library search
+    - icon: simple/streamlit
+      link: https://www.nb.no/dh-lab/apper/
+      name: dhlab streamlit apps
+    - icon: fontawesome/brands/github
+      link: https://github.com/NationalLibraryOfNorway/DHLAB
+    - icon: simple/python
+      link: https://pypi.org/project/dhlab/
+      name: pypi.org
+    - icon: material/bug
+      link: https://github.com/NationalLibraryOfNorway/DHLAB/issues
+      name: bug tracker
+
+plugins:
+  - mkdocstrings
+  - search
+  - autorefs
+  - section-index
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - toc:
+      permalink: true
+
+nav:
+  - Home: index.md
+  - Code Reference:
+    - reference.md
+    - api.md
+    - images.md
+    - metadata.md
+    - ngram.md
+    - text.md
+

pyproject.toml

@@ -30,7 +30,7 @@ pandas = "^2.1.2"
 python-louvain = "^0.16"
 requests = "^2.31.0"
 seaborn = "^0.13.0"
-scipy = "^1.11.3"
+scipy = { version = "^1.11.3", python = ">=3.9,<3.13" }
 openpyxl = "^3.1.2"
 beautifulsoup4 = "^4.12.2"
 numpy = "^1.26.3"
@@ -44,7 +44,11 @@ sphinx-copybutton = "^0.5.2"
 sphinx-togglebutton = "^0.3.2"
 sphinx_design = "^0.5.0"
 sphinx_inline_tabs = "^2023.4.21"
-numpy = "^1.26.1"
+mkdocs = "^1.5.2"
+mkdocstrings = {extras = ["python"], version = "^0.22.0"}
+mkdocs-material = "^9.1.21"
+mkdocs-section-index = "^0.3.5"
+mkdocs-autorefs = "^0.5.0"
 
 [tool.poetry.group.dev.dependencies]
 ipykernel = "^6.26.0"
@@ -67,6 +71,10 @@ bump  = false
 vcs = "git"
 format = "v{base}{stage}{revision}"
 
+
+[tool.poetry-dynamic-versioning.substitution]
+files = ["dhlab/_version.py"]
+
 [build-system]
 requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning"]
 build-backend = "poetry_dynamic_versioning.backend"