Merge pull request #999 from Andries-Smit/automation/build

Add doc health info; error, warning, broken link
openaps · Feb 16, 2021 · 59bdeca · 59bdeca
2 parents e5984c6 + e9f8caf
commit 59bdeca
Show file tree

Hide file tree

Showing 8 changed files with 284 additions and 11 deletions.
diff --git a/.github/workflows/build-warnings.yml b/.github/workflows/build-warnings.yml
@@ -0,0 +1,96 @@
+name: Build Warnings
+
+on:
+  push:
+    branches:
+      - master
+
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [en, fr, de, nl, cs, el, es, ko, lt, ru]
+
+    steps:
+      - uses: actions/checkout@v1
+
+      - name: Set up Python 3.7
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.7"
+
+      - name: Install packages
+        run: |
+          python -m pip install --exists-action=w --no-cache-dir -r requirements.rtd.txt
+          python -m pip install --exists-action=w --no-cache-dir -r requirements.txt
+
+      - name: Set doc Path
+        run: |
+          if [ '${{ matrix.language }}' == 'en' ]
+          then
+            echo "DOC_PATH=docs/EN/" >> $GITHUB_ENV
+          else
+            echo "DOC_PATH=docs/CROWDIN/${{ matrix.language }}/" >> $GITHUB_ENV
+          fi
+
+      - name: Show Sphinx conf
+        run: |
+          cat ${{ env.DOC_PATH }}conf.py
+          cat docs/shared.conf.py
+
+      - name: Build docs
+        run: |
+          cd ${{ env.DOC_PATH }}
+          sphinx-build -T -E -n -v -w build_log.txt -q -b html -d _build/doctrees . _build/html
+      
+      - name: Store build log
+        uses: actions/upload-artifact@v2
+        with:
+          name: build_log_${{ matrix.language }}
+          path: ${{ env.DOC_PATH }}build_log.txt
+
+  badge:
+    needs: build
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      max-parallel: 1
+      matrix:
+        language: [en, fr, de, nl, cs, el, es, ko, lt, ru]
+
+    steps:
+      - name: Get build log
+        uses: actions/download-artifact@v2
+        with:
+          name: build_log_${{ matrix.language }}
+
+      - name: Process - Build results
+        run: |
+          COUNT=$(wc -l < build_log.txt)
+          if [ $COUNT == 0 ]
+          then
+            echo "MESSAGE=OK" >> $GITHUB_ENV
+            echo "COLOR=green" >> $GITHUB_ENV
+          else
+            echo Number of warning $COUNT
+            echo "MESSAGE=$COUNT" >> $GITHUB_ENV
+            echo "COLOR=red" >> $GITHUB_ENV
+          fi
+
+      - if: ${{ always() }}
+        name: Create Badge - Build warnings
+        uses: schneegans/dynamic-badges-action@v1.0.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: 4d086495590ccb904468b66aecc48bdb
+          filename: AndroidAPSdocs_build_warnings_${{ matrix.language }}_master.json
+          label: Warnings - ${{ matrix.language }}
+          message: ${{ env.MESSAGE }}
+          color: ${{ env.COLOR }}
+          namedLogo: read the docs
diff --git a/.github/workflows/link-checker.yml b/.github/workflows/link-checker.yml
@@ -0,0 +1,105 @@
+name: Link Checker
+
+on:
+  push:
+    branches:
+      - master
+
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      max-parallel: 0
+      matrix:
+        language: [en, fr, de, nl, cs, el, es, ko, lt, ru]
+
+    steps:
+      - uses: actions/checkout@v1
+
+      - name: Set up Python 3.7
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.7"
+
+      - name: Install packages
+        run: |
+          python -m pip install --exists-action=w --no-cache-dir -r requirements.rtd.txt
+          python -m pip install --exists-action=w --no-cache-dir -r requirements.txt
+
+      - name: Doc doc Path
+        run: |
+          if [ '${{ matrix.language }}' == 'en' ]
+          then
+            echo "DOC_PATH=docs/EN/" >> $GITHUB_ENV
+          else
+            echo "DOC_PATH=docs/CROWDIN/${{ matrix.language }}/" >> $GITHUB_ENV
+          fi
+
+      - name: Show Sphinx conf
+        run: |
+          cat ${{ env.DOC_PATH }}conf.py
+          cat docs/shared.conf.py
+
+      - name: Build docs
+        run: |
+          cd ${{ env.DOC_PATH }}
+          sphinx-build -T -E -n -v -q -b html -d _build/doctrees . _build/html
+
+      - name: Link Checker
+        env:
+          INPUT_URL: http://localhost:8000
+          INPUT_PAGES_PATH: ${{ env.DOC_PATH }}_build/html
+          INPUT_CMD_PARAMS: --skip-tls-verification -t=30 --color=always -e=.*poctechcorp.* -e=.*wearos.* -e=.*github.* -e=.*herokuapp.* -e=.*tomato.* -e=.*sooil.* -e=.*twitter.* -e.*discord.*
+        run: wget -qO- https://raw.githubusercontent.com/ruzickap/action-my-broken-link-checker/v2.1.0/entrypoint.sh | bash 2>&1 | tee link_log.txt
+
+      - name: Store link log
+        uses: actions/upload-artifact@v2
+        with:
+          name: link_log_${{ matrix.language }}
+          path: link_log.txt
+
+  badge:
+    needs: check
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      max-parallel: 1
+      matrix:
+        language: [en, fr, de, nl, cs, el, es, ko, lt, ru]
+
+    steps:
+      - name: Get link log
+        uses: actions/download-artifact@v2
+        with:
+          name: link_log_${{ matrix.language }}
+
+      - name: Process - Link checker results
+        run: |
+          COUNT=$(grep '\[31' link_log.txt | wc -l)
+          if [ $COUNT == 0 ]
+          then
+            echo "MESSAGE_LINKS=None" >> $GITHUB_ENV
+            echo "COLOR_LINKS=green" >> $GITHUB_ENV
+          else
+            echo Number of broken links: $COUNT
+            echo "MESSAGE_LINKS=$COUNT" >> $GITHUB_ENV
+            echo "COLOR_LINKS=red" >> $GITHUB_ENV
+          fi
+
+      - if: ${{ always() }}
+        name: Create Badge - Link Checker
+        uses: schneegans/dynamic-badges-action@v1.0.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: fc7bdcb3bc52e1ae006b2435ac6001b4
+          filename: AndroidAPSdocs_broken_links_${{ matrix.language }}_master.json
+          label: Broken links - ${{ matrix.language }}
+          message: ${{ env.MESSAGE_LINKS }}
+          color: ${{ env.COLOR_LINKS }}
+          logoSvg: "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'><!-- Font Awesome Free 5.15.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) --><path d='M326.612 185.391c59.747 59.809 58.927 155.698.36 214.59-.11.12-.24.25-.36.37l-67.2 67.2c-59.27 59.27-155.699 59.262-214.96 0-59.27-59.26-59.27-155.7 0-214.96l37.106-37.106c9.84-9.84 26.786-3.3 27.294 10.606.648 17.722 3.826 35.527 9.69 52.721 1.986 5.822.567 12.262-3.783 16.612l-13.087 13.087c-28.026 28.026-28.905 73.66-1.155 101.96 28.024 28.579 74.086 28.749 102.325.51l67.2-67.19c28.191-28.191 28.073-73.757 0-101.83-3.701-3.694-7.429-6.564-10.341-8.569a16.037 16.037 0 0 1-6.947-12.606c-.396-10.567 3.348-21.456 11.698-29.806l21.054-21.055c5.521-5.521 14.182-6.199 20.584-1.731a152.482 152.482 0 0 1 20.522 17.197zM467.547 44.449c-59.261-59.262-155.69-59.27-214.96 0l-67.2 67.2c-.12.12-.25.25-.36.37-58.566 58.892-59.387 154.781.36 214.59a152.454 152.454 0 0 0 20.521 17.196c6.402 4.468 15.064 3.789 20.584-1.731l21.054-21.055c8.35-8.35 12.094-19.239 11.698-29.806a16.037 16.037 0 0 0-6.947-12.606c-2.912-2.005-6.64-4.875-10.341-8.569-28.073-28.073-28.191-73.639 0-101.83l67.2-67.19c28.239-28.239 74.3-28.069 102.325.51 27.75 28.3 26.872 73.934-1.155 101.96l-13.087 13.087c-4.35 4.35-5.769 10.79-3.783 16.612 5.864 17.194 9.042 34.999 9.69 52.721.509 13.906 17.454 20.446 27.294 10.606l37.106-37.106c59.271-59.259 59.271-155.699.001-214.959z'/></svg>"
+
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,6 @@
+_build/
+docs/_build/
+docs/EN/_build/
+docs/CROWDIN/fr/_build/
+docs/CROWDIN/de/_build/
+docs/CROWDIN/nl/_build/
diff --git a/README.md b/README.md
@@ -1,4 +1,70 @@
 # AndroidAPSdocs
+
 Documentation for AndroidAPS
 
-To view docs visit https://androidaps.readthedocs.io/
+To view documentation visit https://androidaps.readthedocs.io/
+
+## Docs Status
+
+| Language | Build | Warning | Links |
+| -------- | ----- | ------- | ----- |
+| [English](https://androidaps.readthedocs.io/en/latest/)    | [![Documentation Status](https://readthedocs.org/projects/androidaps/badge/?version=latest)](https://readthedocs.org/projects/androidaps/builds/)       | [![Build Warnings - en](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_en_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - en](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_en_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [German](https://androidaps.readthedocs.io/de/latest/)     | [![Documentation Status](https://readthedocs.org/projects/androidaps-de/badge/?version=latest)](https://readthedocs.org/projects/androidaps-de/builds/) | [![Build Warnings - de](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_de_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - de](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_de_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [Dutch](https://androidaps.readthedocs.io/nl/latest/)      | [![Documentation Status](https://readthedocs.org/projects/androidaps-nl/badge/?version=latest)](https://readthedocs.org/projects/androidaps-nl/builds/) | [![Build Warnings - nl](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_nl_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - nl](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_nl_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [Czech](https://androidaps.readthedocs.io/cs/latest/)      | [![Documentation Status](https://readthedocs.org/projects/androidaps-cs/badge/?version=latest)](https://readthedocs.org/projects/androidaps-cs/builds/) | [![Build Warnings - cs](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_cs_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - cs](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_cs_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [Greek](https://androidaps.readthedocs.io/el/latest/)      | [![Documentation Status](https://readthedocs.org/projects/androidaps-el/badge/?version=latest)](https://readthedocs.org/projects/androidaps-el/builds/) | [![Build Warnings - el](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_el_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - el](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_el_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [Spanish](https://androidaps.readthedocs.io/es/latest/)    | [![Documentation Status](https://readthedocs.org/projects/androidaps-es/badge/?version=latest)](https://readthedocs.org/projects/androidaps-es/builds/) | [![Build Warnings - es](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_es_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - es](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_es_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [Korean](https://androidaps.readthedocs.io/ko/latest/)     | [![Documentation Status](https://readthedocs.org/projects/androidaps-ko/badge/?version=latest)](https://readthedocs.org/projects/androidaps-ko/builds/) | [![Build Warnings - ko](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_ko_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - ko](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_ko_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [Lithuanian](https://androidaps.readthedocs.io/lt/latest/) | [![Documentation Status](https://readthedocs.org/projects/androidaps-lt/badge/?version=latest)](https://readthedocs.org/projects/androidaps-lt/builds/) | [![Build Warnings - lt](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_lt_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - lt](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_lt_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+| [Russian](https://androidaps.readthedocs.io/ru/latest/)    | [![Documentation Status](https://readthedocs.org/projects/androidaps-ru/badge/?version=latest)](https://readthedocs.org/projects/androidaps-ru/builds/) | [![Build Warnings - ru](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/4d086495590ccb904468b66aecc48bdb/raw/AndroidAPSdocs_build_warnings_ru_master.json)](../../../actions?query=workflow%3A%22Build+Warnings%22) | [![Link Checker - ru](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Andries-Smit/fc7bdcb3bc52e1ae006b2435ac6001b4/raw/AndroidAPSdocs_broken_links_ru_master.json)](../../../actions?query=workflow%3A%22Link+Checker%22) |
+
+
+**Note** Issues in the source language "English" should be fixed in (GitHub)[https://github.com/openaps/AndroidAPSdocs]. Issues in translation should be fixed via [CROWDIN](https://crowdin.com/project/androidapsdocs) platform.
+
+### Build and Warning
+
+The current build logs of the documentation can be found at on the documentation hosting site, by clicking the **docs** badge in the column **Build**.  
+
+In the project open the menu **Builds** section of the documentation, select top **Passed version latest (html)** and select **View raw** or click at the bottom grey bar **/home/docs/....**  
+
+The badges are generated with a [GitHub Action](../../../actions), and the can be inspected for more details, by clicking on the status badge or [here](../../../actions?query=workflow%3A%22Build+Warnings%22).
+
+* Select top workflow **Build warning**
+* Select the build of a language, for example **build (de)**
+* Click on the section **Build docs** to see build output
+
+### Broken Links
+
+The badges are generated with a [GitHub Action](../../../actions), and the output can be inspected for more details, or by clicking on the status badge, or [here](../../../actions?query=workflow%3A%22Link+Checker%22).
+
+* Select top workflow **Link Checker**
+* Select the build of a language, for example **check (de)**
+* Click on the section **Link Checker** to see link checker output
+
+**Note:** Links that always failed, but are working correctly should be excluded in the check. Please raise an issue, on one of the channels, or open a pull request in the [flow](https://github.com/openaps/AndroidAPSdocs/.github/workflows/link-checker.yml#L56).
+
+### Most common issues
+
+The most issues are in restructured text:
+
+- Title underline are too short; they should be at least as long as the title
+- Missing new line, after list
+- links are broken, OK `` `Link text <link URL>`_``
+  - Replaced back quote \` by another type of quote: `` 'Link text <link URL>"_``
+  - Missing space before < link  `` `Linktext<link URL>`_``
+  - Extra space after > link  `` `Linktext <link URL> `_``
+  - Extra space after \` back tick  `` `Linktext <link URL>` _``
+- Closing italic or bold text is not done, or a space is added before or after
+    - OK `**My bold text**`
+    - Not OK `** My broken bold text **`
+- Markdown syntax  is used in rst files, they are not compatible.
+- Directive are translated, https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
+
+### Link issues
+
+The link checker validates both internal and external links. Most common issues:
+
+- Translation headers, cause link anchor form other pages to be broken
+- External links are changes
+- Link checker receives a redirect on external page
+- Link anchor to was generated on page load (have to be excluded)
diff --git a/docs/EN/Configuration/Config-Builder.md b/docs/EN/Configuration/Config-Builder.md
@@ -158,7 +158,7 @@ For dana pumps, use <b>Advanced settings</b> to activate BT watchdog if necessar
 [Password for Dana RS pump](../Configuration/DanaRS-Insulin-Pump.md) must be entered correctly. Password was not checked in previous versions.
 
 ## Sensitivity Detection
-Select the type of sensitivity detection. For more details of different designs please [read on here](../Configuration/Sensitivity-detection-and-COB.md). This will analyze historical data on the go and make adjustments if it recognizes that you are reacting more sensitively (or conversely, more resistant) to insulin than usual.  More details about the Sensitivity algorithm can be read in the [OpenAPS docs](https://openaps.readthedocs.io/en/latest/docs/walkthrough/phase-4/advanced-features.html#auto-sensitivity-mode).  
+Select the type of sensitivity detection. For more details of different designs please [read on here](../Configuration/Sensitivity-detection-and-COB.md). This will analyze historical data on the go and make adjustments if it recognizes that you are reacting more sensitively (or conversely, more resistant) to insulin than usual.  More details about the Sensitivity algorithm can be read in the [OpenAPS docs](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autosens.html).  
 
 You can view your sensitivity on the homescreen by selecting SEN and watching the white line.  Note, you need to be in [Objective 8](../Usage/Objectives#objective-8-adjust-basals-and-ratios-if-needed-and-then-enable-autosens) in order to let Sensitivity Detection/[Autosens](../Usage/Open-APS-features#autosens) automatically adjust the amount of insulin delivered. Before reaching that objective, the Autosens percentage / the line in your graph is displayed for information only.
 

diff --git a/docs/EN/Installing-AndroidAPS/Building-APK.md b/docs/EN/Installing-AndroidAPS/Building-APK.md
@@ -144,7 +144,7 @@ On the Android Studio welcome screen click the small triangle (1. in next screen
 
 * Do not click "Background" while repository is cloned!
 
-   ![No background action](../images/AndroidStudio_NoBackground.png)
+   ![No background action](../images/AndroidStudio361_15.png)
 
 * After repository is cloned successfully open your local copy by clicking "Yes".
 

diff --git a/docs/shared.conf.py b/docs/shared.conf.py
@@ -132,13 +132,6 @@
 # alabaster
 theme_github_user = 'openAPS'
 theme_github_repo = 'AndroidAPSdocs'
-html_theme_options = {
-  'show_related': True,
-  'github_user': theme_github_user,
-  'github_repo': theme_github_repo,
-  'prev_next_buttons_location': None,
-  'navigation_depth': 6,
-}
 
 """
 html_theme = 'default'
@@ -384,4 +377,3 @@ def setup(app):
             'enable_eval_rst': True,
             }, True)
     app.add_transform(AutoStructify)
-
diff --git a/requirements.rtd.txt b/requirements.rtd.txt
@@ -0,0 +1,8 @@
+# Standard dependencies installed by RTD
+setuptools==41.0.1
+mock==1.0.1
+pillow==5.4.1
+setuptools==41.0.1
+mock==1.0.1
+sphinx-rtd-theme
+readthedocs-sphinx-ext