diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..33cf83f --- /dev/null +++ b/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 +``` diff --git a/docs/api_reference/python_utils/choices.md b/docs/api_reference/python_utils/choices.md new file mode 100644 index 0000000..1ffce36 --- /dev/null +++ b/docs/api_reference/python_utils/choices.md @@ -0,0 +1 @@ +::: python_utils.choices diff --git a/docs/api_reference/python_utils/data_structures.md b/docs/api_reference/python_utils/data_structures.md new file mode 100644 index 0000000..5bc5519 --- /dev/null +++ b/docs/api_reference/python_utils/data_structures.md @@ -0,0 +1 @@ +::: python_utils.data_structures diff --git a/docs/api_reference/python_utils/db.md b/docs/api_reference/python_utils/db.md new file mode 100644 index 0000000..b2ce515 --- /dev/null +++ b/docs/api_reference/python_utils/db.md @@ -0,0 +1 @@ +::: python_utils.db diff --git a/docs/api_reference/python_utils/django_utils.md b/docs/api_reference/python_utils/django_utils.md new file mode 100644 index 0000000..d08df9f --- /dev/null +++ b/docs/api_reference/python_utils/django_utils.md @@ -0,0 +1 @@ +::: python_utils.django_utils diff --git a/docs/api_reference/python_utils/esma_choices.md b/docs/api_reference/python_utils/esma_choices.md new file mode 100644 index 0000000..91dcc03 --- /dev/null +++ b/docs/api_reference/python_utils/esma_choices.md @@ -0,0 +1 @@ +::: python_utils.esma_choices diff --git a/docs/api_reference/python_utils/exceptions.md b/docs/api_reference/python_utils/exceptions.md new file mode 100644 index 0000000..88d4530 --- /dev/null +++ b/docs/api_reference/python_utils/exceptions.md @@ -0,0 +1 @@ +::: python_utils.exceptions diff --git a/docs/api_reference/python_utils/imports.md b/docs/api_reference/python_utils/imports.md new file mode 100644 index 0000000..2250793 --- /dev/null +++ b/docs/api_reference/python_utils/imports.md @@ -0,0 +1 @@ +::: python_utils.imports diff --git a/docs/api_reference/python_utils/math.md b/docs/api_reference/python_utils/math.md new file mode 100644 index 0000000..9ae22e9 --- /dev/null +++ b/docs/api_reference/python_utils/math.md @@ -0,0 +1 @@ +::: python_utils.math diff --git a/docs/api_reference/python_utils/pandas_utils.md b/docs/api_reference/python_utils/pandas_utils.md new file mode 100644 index 0000000..d00f360 --- /dev/null +++ b/docs/api_reference/python_utils/pandas_utils.md @@ -0,0 +1 @@ +::: python_utils.pandas_utils diff --git a/docs/api_reference/python_utils/rest.md b/docs/api_reference/python_utils/rest.md new file mode 100644 index 0000000..e47d626 --- /dev/null +++ b/docs/api_reference/python_utils/rest.md @@ -0,0 +1 @@ +::: python_utils.rest diff --git a/docs/api_reference/python_utils/text.md b/docs/api_reference/python_utils/text.md new file mode 100644 index 0000000..ec802b4 --- /dev/null +++ b/docs/api_reference/python_utils/text.md @@ -0,0 +1 @@ +::: python_utils.text diff --git a/docs/api_reference/python_utils/time.md b/docs/api_reference/python_utils/time.md new file mode 100644 index 0000000..5c912ce --- /dev/null +++ b/docs/api_reference/python_utils/time.md @@ -0,0 +1 @@ +::: python_utils.time diff --git a/docs/api_reference/python_utils/types_hinting.md b/docs/api_reference/python_utils/types_hinting.md new file mode 100644 index 0000000..5baa4db --- /dev/null +++ b/docs/api_reference/python_utils/types_hinting.md @@ -0,0 +1 @@ +::: python_utils.types_hinting diff --git a/docs/assets/cardoai_logo.png b/docs/assets/cardoai_logo.png new file mode 100644 index 0000000..63f914d Binary files /dev/null and b/docs/assets/cardoai_logo.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..000ea34 --- /dev/null +++ b/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. diff --git a/justfile b/justfile new file mode 100644 index 0000000..caed9ab --- /dev/null +++ b/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 . diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..2a8e055 --- /dev/null +++ b/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/