diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml
index a2e3b93..9648e9f 100644
--- 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
index b6d031a..165671b 100644
--- 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
\ No newline at end of file
diff --git a/docs/README.md b/README.md
similarity index 67%
rename from docs/README.md
rename to README.md
index d779718..39970b3 100644
--- a/docs/README.md
+++ b/README.md
@@ -1,3 +1,18 @@
+
+
+
+
+
+
+
+
+## About Repo
+
+
+
+
+
+
# 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)
-
-
-
-
## Contributors
diff --git a/build_mkdocs.sh b/build_mkdocs.sh
new file mode 100644
index 0000000..d7d7552
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/how-to-guides/CONTRIBUTING.md b/docs/how-to-guides/CONTRIBUTING.md
index dd5e69b..f339045 100644
--- a/docs/how-to-guides/CONTRIBUTING.md
+++ b/docs/how-to-guides/CONTRIBUTING.md
@@ -53,15 +53,12 @@ git push origin //{}
- [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
index 6c38dd5..14f7314 100644
--- 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
index 4782fbe..0e77762 100644
--- 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
index 97e23cb..c00dbf5 100644
--- 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
index 3ffa1d5..1609a43 100644
--- 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
\ No newline at end of file
+ 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
\ No newline at end of file
+