fix: build mkdocs script and update doc (#68)

* build mkdocs script for placing README.md at the root * Update the docs * Add "make all" to ease the setup locally (for new contributors)
openfoodfacts · Nov 30, 2022 · 9d05f20 · 9d05f20
1 parent e8b1508
commit 9d05f20
Show file tree

Hide file tree

Showing 9 changed files with 78 additions and 23 deletions.
diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml
@@ -25,9 +25,13 @@ jobs:
         with:
           python-version: 3.x
       - name: Install mkdocs requirements
-        run: pip install mkdocs-material
+        run: |
+          pip install mkdocs-material
+          pip install mdx_truly_sane_lists
       - name: Generate documentation
-        run: mkdocs build
+        run: |
+          bash ./build_mkdocs.sh
+          mkdocs build
       - name: Deploy documentation to Github Pages 🚀
         # we only deploy on push to main
         if: |

diff --git a/Makefile b/Makefile
@@ -30,3 +30,6 @@ tests:
 	${DOCKER_RUN} pytest .
 
 checks: quality tests
+
+# To ease the process for contributors
+all: build_lang lint checks
diff --git a/docs/README.md → README.md b/docs/README.md → README.md
@@ -1,3 +1,18 @@
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://static.openfoodfacts.org/images/logos/off-logo-horizontal-dark.png?refresh_github_cache=1">
+  <source media="(prefers-color-scheme: light)" srcset="https://static.openfoodfacts.org/images/logos/off-logo-horizontal-light.png?refresh_github_cache=1">
+  <img height="80" src="https://static.openfoodfacts.org/images/logos/off-logo-horizontal-light.svg">
+</picture>  
+</p>
+
+## About Repo
+
+![GitHub language count](https://img.shields.io/github/languages/count/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=brightgreen)
+![GitHub top language](https://img.shields.io/github/languages/top/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=aqua)
+![GitHub last commit](https://img.shields.io/github/last-commit/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=blue)
+![Github Repo Size](https://img.shields.io/github/repo-size/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=aqua)
+
 # facets-knowledge-panels
 
 Providing knowledge panels for a particular Open Food Facts facet (category, brand, etc...)
@@ -12,17 +27,11 @@ Providing knowledge panels for a particular Open Food Facts facet (category, bra
 
 - Join us on [Slack](https://openfoodfacts.slack.com/archives/C03LFRKLVBQ)
 - Developer documentation
-    - [Project setup](./how-to-guides/Project-setup-locally.md)
-    - [Testing](./how-to-guides/Testing.md)
-    - [Contributing Guidelines](./how-to-guides/CONTRIBUTING.md)
-- [API Documentation](./references/API%20references.md)
-
-## About Repo
+    - [Project setup](./docs/how-to-guides/Project-setup-locally.md)
+    - [Testing](./docs/how-to-guides/Testing.md)
+    - [Contributing Guidelines](./docs/how-to-guides/CONTRIBUTING.md)
+- [API Documentation](./docs/references/API%20references.md)
 
-![GitHub language count](https://img.shields.io/github/languages/count/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=brightgreen)
-![GitHub top language](https://img.shields.io/github/languages/top/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=aqua)
-![GitHub last commit](https://img.shields.io/github/last-commit/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=blue)
-![Github Repo Size](https://img.shields.io/github/repo-size/openfoodfacts/facets-knowledge-panels?style=for-the-badge&color=aqua)
 
 ## Contributors
 

diff --git a/build_mkdocs.sh b/build_mkdocs.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+# Renders markdown doc in docs to html in gh_pages
+
+# copy README.md as the index but change links starting with ./docs/ to ./
+sed -e 's|(\./docs/|(./|g' README.md > docs/index.md
diff --git a/docs/how-to-guides/CONTRIBUTING.md b/docs/how-to-guides/CONTRIBUTING.md
@@ -53,15 +53,12 @@ git push origin <type>/<issue-issueNumber>/{<additional-fixes>}
 - [Setup project locally](./Project-setup-locally.md)
 
 #### Step 3
+- [Testing the work before push](./Testing.md)
+
+#### Step 4
 ```bash
 ## Committing and pushing your work
 
-# recompile languages files
-make build_lang
-
-# format your code
-make checks
-
 # Ensure branch
 git branch
 

diff --git a/docs/how-to-guides/Project-setup-locally.md b/docs/how-to-guides/Project-setup-locally.md
@@ -1,7 +1,7 @@
 # Project Setup
 You may choose Docker-compose(recommended), or Through virtual env 
 
-### Through Docker
+### Through Docker[Recommended]
 
 - Prerequisite - [Docker](https://docs.docker.com/get-docker/)
 
@@ -11,11 +11,19 @@ to build:
 ```bash
 docker-compose build
 ```
+or
+```bash
+make docker_build
+```
 
 to run:
 ```bash
 docker-compose up
 ```
+or
+```bash
+make docker_up
+```
 
 - Visit `http://127.0.0.1/` with the endpoints or /docs for documentation
 

diff --git a/docs/how-to-guides/Testing.md b/docs/how-to-guides/Testing.md
@@ -2,15 +2,17 @@
 
 ### docker setup
 ```bash
+make build_lang
 docker-compose run --rm facets-api pytest tests
 ```
 or
 ```bash
-make tests
+make all
 ```
 
 ### virtual env setup
 - Checkout `tests` directory
 ```bash
+make build_lang
 pytest 
 ```
diff --git a/docs/references/API references.md b/docs/references/API references.md
@@ -4,6 +4,6 @@ Knowledge panel facets is a simple api that allow user to get knowledge-panels b
 
 The api must be prefixed with this `/knowledge_panel?`.
 The full url look like 
-`http://127.0.0.1:8000/knowledge_panel?facet_tag={desired-facet}&value_tag={facet-value}&lang_code={language}&country={desired-country}`
+` https://facets-kp.openfoodfacts.org/knowledge_panel?facet_tag={desired-facet}&value_tag={facet-value}&lang_code={language}&country={desired-country}`
 
-- API Documentation with interactive "try-out": http://127.0.0.1:8000/docs
+- API Documentation with interactive "try-out": https://facets-kp.openfoodfacts.org/docs
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,4 +9,30 @@ repo_url: https://github.com/openfoodfacts/facets-knowledge-panels
 edit_uri: blob/main/docs/
 
 theme:
-  name: material
+  name: material
+  logo: https://static.openfoodfacts.org/images/logos/off-logo-horizontal-light.svg
+  favicon: https://static.openfoodfacts.org/images/logos/off-logo-favicon-light.png
+  palette: 
+
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7 
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+markdown_extensions:
+  - footnotes
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - toc:
+      # add permalink after titles
+      permalink: "#"
+      # this one allow to have two space indentation
+  # counts as nested list
+  - mdx_truly_sane_lists