mkdocs static site generation for docs and automatic API Reference generation

docs/README.md

@@ -0,0 +1,40 @@
+# Documentation and API Reference
+
+In order to edit documentation, it is recommended to use the following `mamba`/`conda` environment:
+
+```shell
+# create environment named "mkdocs" with dependencies
+mamba create -n mkdocs -y -c conda-forge mkdocs-material mkdocstrings-python mike go-yq just sd fd
+
+# autogenerate api reference according to just recipe in justfile
+mamba run -n mkdocs just make-api-reference-in-docs
+
+# start development server
+mamba run -n mkdocs serve
+```
+
+Now you can add/edit markdown files in the `docs/` directory and you need to make sure that these files are referenced in the `nav` section of the `mkdocs.yml` file in order to be able to see them.
+
+> The auto-generation of the API Reference populates the nav section of the `mkdocs.yml` using `yq`
+
+Useful links to get you started with mkdocs to write documentation are:
+
+1. [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
+2. [mkdocs](https://www.mkdocs.org/)
+
+## API Reference auto-generation
+
+It follows the script specified in the [justfile](../justfile). It
+
+- copies the same tree structure of the library
+- injects the `:::` directive to the markdown file corresponding to the submodule
+- references the markdown files in the `mkdocs.yml`
+
+## Deployment of docs
+
+Running the command `mkdocs build` will statically generate the html files in the `site/` directory. The docs can be served as a docker image with the following Dockerfile (once the docs are built of course)
+
+```Dockerfile
+FROM nginx:latest
+COPY site /usr/share/nginx/html
+```

docs/api_reference/python_utils/choices.md

@@ -0,0 +1 @@
+::: python_utils.choices

docs/api_reference/python_utils/data_structures.md

@@ -0,0 +1 @@
+::: python_utils.data_structures

docs/api_reference/python_utils/db.md

@@ -0,0 +1 @@
+::: python_utils.db

docs/api_reference/python_utils/django_utils.md

@@ -0,0 +1 @@
+::: python_utils.django_utils

docs/api_reference/python_utils/esma_choices.md

@@ -0,0 +1 @@
+::: python_utils.esma_choices

docs/api_reference/python_utils/exceptions.md

@@ -0,0 +1 @@
+::: python_utils.exceptions

docs/api_reference/python_utils/imports.md

@@ -0,0 +1 @@
+::: python_utils.imports

docs/api_reference/python_utils/math.md

@@ -0,0 +1 @@
+::: python_utils.math

docs/api_reference/python_utils/pandas_utils.md

@@ -0,0 +1 @@
+::: python_utils.pandas_utils

docs/api_reference/python_utils/rest.md

@@ -0,0 +1 @@
+::: python_utils.rest

docs/api_reference/python_utils/text.md

@@ -0,0 +1 @@
+::: python_utils.text

docs/api_reference/python_utils/time.md

@@ -0,0 +1 @@
+::: python_utils.time

docs/api_reference/python_utils/types_hinting.md

@@ -0,0 +1 @@
+::: python_utils.types_hinting

docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

justfile

@@ -0,0 +1,49 @@
+default:
+  just --list
+
+lib_name := "python_utils"
+
+make-api-reference-in-docs:
+  #!/usr/bin/zsh
+  # reset destination directory
+  rm -r docs/api_reference/{{ lib_name }} || printf ""
+  cp -r {{ lib_name }} docs/api_reference/{{ lib_name }}
+
+  # remove files that must not belong to the documentation
+  fd -I -td "__pycache__"  docs/api_reference/{{ lib_name }}/ -x rm -r {}
+  fd -I -tf __init__.py docs/api_reference/{{ lib_name }} -x rm {}
+  # this one deletes README.md files
+  fd -I -tf -e md . docs/api_reference/{{ lib_name }} -x rm {}
+
+  # replace file extensions
+  fd -tf -e py . docs/api_reference/{{ lib_name }} -x rename '.py' '.md' {}
+
+  # inject module path into the markdown files for generation of API reference
+  for file in `fd -tf -e md . docs/api_reference/{{ lib_name }} | xargs`; do \
+    module_path=`echo $file | sd 'docs/api_reference/' '::: ' | sd '.md' '' | sd '/' '.'`; \
+    echo $module_path > $file; \
+  done
+
+  # reset the path of the API reference to null, for the sake of making it work
+  # since yq would expect integer indexing and we ll be doing string indexing
+  # in the for loop
+  # note that if you re doing a different layout of the documentation, you need to
+  # change the location of the API Reference to how you set it
+  api_reference_key='.nav[1].["API Reference"][0]'
+  yq -i "$api_reference_key=null" mkdocs.yml
+
+  # repopulate mkdocs.yml
+  for md_file in `fd -tf -e md . docs/api_reference/{{ lib_name }}`; do
+    # get keypath
+    keypath=.`echo $md_file | sd '(docs/api_reference/|.md)' '' | sd '/' '.'`
+    # get corrected filepath
+    filepath_value=`echo $md_file | sd 'docs/' ''`
+    echo $keypath
+    echo $filepath_value
+    yq -i "$api_reference_key$keypath = \"$filepath_value\"" mkdocs.yml
+    echo
+  done;
+
+docs-docker-image := "mkdocs-material"
+build-docs-image:
+  docker build -t {{docs-docker-image}} -f Dockerfile.docs .

mkdocs.yml

@@ -0,0 +1,70 @@
+site_name: CardoAI Python Utils
+repo_url: https://github.com/CardoAI/cardo-python-utils
+repo_name: cardo-python-utils
+nav:
+  - Home: index.md
+  - API Reference:
+      - python_utils:
+          choices: api_reference/python_utils/choices.md
+          data_structures: api_reference/python_utils/data_structures.md
+          db: api_reference/python_utils/db.md
+          django_utils: api_reference/python_utils/django_utils.md
+          esma_choices: api_reference/python_utils/esma_choices.md
+          exceptions: api_reference/python_utils/exceptions.md
+          imports: api_reference/python_utils/imports.md
+          math: api_reference/python_utils/math.md
+          pandas_utils: api_reference/python_utils/pandas_utils.md
+          rest: api_reference/python_utils/rest.md
+          text: api_reference/python_utils/text.md
+          time: api_reference/python_utils/time.md
+          types_hinting: api_reference/python_utils/types_hinting.md
+theme:
+  name: material
+  logo: assets/cardoai_logo.png
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      accent: deep orange
+      primary: deep purple
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      accent: deep orange
+      primary: deep purple
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+  font:
+    code: JetBrains Mono
+    text: Roboto Slab
+  features:
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - toc.follow
+    - navigation.top
+    - navigation.indexes
+# for different versions of the library
+extra:
+  version:
+    provider: mike
+# for the API reference
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_submodules: true
+  - search
+# for KaTeX
+extra_javascript:
+  - javascripts/katex.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
+extra_css:
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
+exclude:
+  - Dockerfile
+  - k8s/