From 8b7c2cb2193019bf043a4996f24b7a4463da6f2a Mon Sep 17 00:00:00 2001 From: Pierre Slamich Date: Fri, 18 Oct 2024 19:07:34 +0200 Subject: [PATCH 1/2] ci: dartdoc + mkdocs --- .github/workflows/dartdoc.yml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/dartdoc.yml b/.github/workflows/dartdoc.yml index 77185a5a23d..318f2dd3fae 100644 --- a/.github/workflows/dartdoc.yml +++ b/.github/workflows/dartdoc.yml @@ -3,7 +3,6 @@ push: branches: - "develop" - #- "dartdoc-smoothie" jobs: deploy-pages: name: Deploy to GitHub Pages @@ -29,8 +28,14 @@ - name: Run Dartdoc run: pub global activate dartdoc && dartdoc - - name: Deploy API documentation to Github Pages + - name: Deploy smooth_app documentation to Github Pages uses: JamesIves/github-pages-deploy-action@v4.3.3 with: BRANCH: gh-pages - FOLDER: packages/smooth_app/doc/api/ + FOLDER: packages/smooth_app/docs/ + + - name: Deploy scanner documentation to Github Pages + uses: JamesIves/github-pages-deploy-action@v4.3.3 + with: + BRANCH: gh-pages + FOLDER: packages/smooth_app/docs/ From 3d8bd160457f7535516ee35241ab20dc7c557b97 Mon Sep 17 00:00:00 2001 From: Pierre Slamich Date: Fri, 18 Oct 2024 19:16:22 +0200 Subject: [PATCH 2/2] --- .github/workflows/dartdoc.yml | 80 +++++++++++++++++++--------------- packages/smooth_app/README.md | 36 +++++++++++++++ packages/smooth_app/mkdocs.yml | 22 ++++++++++ 3 files changed, 102 insertions(+), 36 deletions(-) create mode 100644 packages/smooth_app/mkdocs.yml diff --git a/.github/workflows/dartdoc.yml b/.github/workflows/dartdoc.yml index 318f2dd3fae..57e5a32e701 100644 --- a/.github/workflows/dartdoc.yml +++ b/.github/workflows/dartdoc.yml @@ -1,41 +1,49 @@ - name: GitHub Pages Deploy Action - on: - push: - branches: - - "develop" - jobs: - deploy-pages: - name: Deploy to GitHub Pages - runs-on: ubuntu-latest - defaults: - run: - working-directory: ./packages/smooth_app - steps: +name: GitHub Pages Deploy Action +on: + push: + branches: + - "develop" +jobs: + deploy-pages: + name: Deploy to GitHub Pages + runs-on: ubuntu-latest + defaults: + run: + working-directory: ./packages/smooth_app + steps: - - name: Chekout code - uses: actions/checkout@v3 + - name: Chekout code + uses: actions/checkout@v3 - - name: Setup Flutter - uses: actions/cache@v3 - with: - path: ${{ runner.tool_cache }}/flutter - key: flutter-2.5.0-stable - - uses: subosito/flutter-action@v2 - with: - channel: stable - flutter-version: 2.5.0 + - name: Setup Flutter + uses: actions/cache@v3 + with: + path: ${{ runner.tool_cache }}/flutter + key: flutter-2.5.0-stable + - uses: subosito/flutter-action@v2 + with: + channel: stable + flutter-version: 2.5.0 - - name: Run Dartdoc - run: pub global activate dartdoc && dartdoc + - name: Run Dartdoc + run: pub global activate dartdoc && dartdoc - - name: Deploy smooth_app documentation to Github Pages - uses: JamesIves/github-pages-deploy-action@v4.3.3 - with: - BRANCH: gh-pages - FOLDER: packages/smooth_app/docs/ + - name: Install mkdocs and mkdocs-material + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material - - name: Deploy scanner documentation to Github Pages - uses: JamesIves/github-pages-deploy-action@v4.3.3 - with: - BRANCH: gh-pages - FOLDER: packages/smooth_app/docs/ + - name: Build documentation using mkdocs + run: mkdocs build + + - name: Deploy smooth_app documentation to Github Pages + uses: JamesIves/github-pages-deploy-action@v4.3.3 + with: + BRANCH: gh-pages + FOLDER: packages/smooth_app/docs/ + + - name: Deploy scanner documentation to Github Pages + uses: JamesIves/github-pages-deploy-action@v4.3.3 + with: + BRANCH: gh-pages + FOLDER: packages/smooth_app/docs/ diff --git a/packages/smooth_app/README.md b/packages/smooth_app/README.md index 7c6a250b160..b86a8853e90 100644 --- a/packages/smooth_app/README.md +++ b/packages/smooth_app/README.md @@ -3,3 +3,39 @@ Submodule containing all the logic of the Smoothie app. In the future, it will receive as parameters: - a barcode decoding algorithm - how to manage the review on the app store + +## Documentation + +We use `mkdocs` for our documentation. `mkdocs` is a static site generator that's geared towards project documentation. It is written in Python. + +### How to use `mkdocs` + +1. Install `mkdocs`: + ```sh + pip install mkdocs mkdocs-material + ``` + +2. Serve the documentation locally: + ```sh + mkdocs serve + ``` + + This will start a local server at `http://127.0.0.1:8000/` where you can view the documentation. + +3. Build the documentation: + ```sh + mkdocs build + ``` + + This will generate a static site in the `site` directory. + +### Deploying the documentation + +We use GitHub Pages to host our documentation. The deployment is handled automatically by a GitHub Actions workflow. + +To manually deploy the documentation, you can use the following command: +```sh +mkdocs gh-deploy +``` + +This will build the documentation and push it to the `gh-pages` branch of the repository. diff --git a/packages/smooth_app/mkdocs.yml b/packages/smooth_app/mkdocs.yml new file mode 100644 index 00000000000..29e3f950ae7 --- /dev/null +++ b/packages/smooth_app/mkdocs.yml @@ -0,0 +1,22 @@ +site_name: Open Food Facts mobile app +docs_dir: doc +repo_url: https://github.com/openfoodfacts/smooth-app +edit_uri: blob/develop/docs/ +site_dir: gh_pages + +theme: + name: material + palette: + primary: beige + text: black + logo: assets/app/logo_text_black.svg + +markdown_extensions: + - footnotes + - mdx_truly_sane_lists + - pymdownx.highlight + - pymdownx.superfences + +plugins: + - awesome-pages + - search