From b29b6f2da9724958088477352dfad0c9731b1db5 Mon Sep 17 00:00:00 2001 From: bgalvao Date: Mon, 24 Jul 2023 14:43:02 +0100 Subject: [PATCH] docs: first docs --- docs/README.md | 40 ++++++++++ docs/api_reference/python_utils/choices.md | 1 + .../python_utils/data_structures.md | 1 + docs/api_reference/python_utils/db.md | 1 + .../python_utils/django_utils.md | 1 + .../python_utils/esma_choices.md | 1 + docs/api_reference/python_utils/exceptions.md | 1 + docs/api_reference/python_utils/imports.md | 1 + docs/api_reference/python_utils/math.md | 1 + .../python_utils/pandas_utils.md | 1 + docs/api_reference/python_utils/rest.md | 1 + docs/api_reference/python_utils/text.md | 1 + docs/api_reference/python_utils/time.md | 1 + .../python_utils/types_hinting.md | 1 + docs/assets/cardoai_logo.png | Bin 0 -> 3549 bytes docs/index.md | 17 +++++ justfile | 49 ++++++++++++ mkdocs.yml | 70 ++++++++++++++++++ 18 files changed, 189 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/api_reference/python_utils/choices.md create mode 100644 docs/api_reference/python_utils/data_structures.md create mode 100644 docs/api_reference/python_utils/db.md create mode 100644 docs/api_reference/python_utils/django_utils.md create mode 100644 docs/api_reference/python_utils/esma_choices.md create mode 100644 docs/api_reference/python_utils/exceptions.md create mode 100644 docs/api_reference/python_utils/imports.md create mode 100644 docs/api_reference/python_utils/math.md create mode 100644 docs/api_reference/python_utils/pandas_utils.md create mode 100644 docs/api_reference/python_utils/rest.md create mode 100644 docs/api_reference/python_utils/text.md create mode 100644 docs/api_reference/python_utils/time.md create mode 100644 docs/api_reference/python_utils/types_hinting.md create mode 100644 docs/assets/cardoai_logo.png create mode 100644 docs/index.md create mode 100644 justfile create mode 100644 mkdocs.yml 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 0000000000000000000000000000000000000000..63f914d130790dc94bef6a66c7ea90cce55ae3b9 GIT binary patch literal 3549 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 puNd-XT;(T2{$DBdf8XhjvP`LvV4KG~ZC`Z5 literal 0 HcmV?d00001 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/