Add a translated, themed mkdocs configuration. (#1)

Author: kattni

.github/dependabot.yml

@@ -0,0 +1,18 @@
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates on Sunday, 8PM UTC
+      interval: "weekly"
+      day: "sunday"
+      time: "20:00"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      # Check for updates on Sunday, 8PM UTC
+      interval: "weekly"
+      day: "sunday"
+      time: "20:00"

.github/workflows/pre-commit-update.yml

@@ -0,0 +1,15 @@
+name: Update pre-commit
+
+on:
+  schedule:
+    - cron: "0 20 * * SUN"  # Sunday @ 2000 UTC
+  workflow_dispatch:
+
+jobs:
+  pre-commit-update:
+    name: Update pre-commit
+    uses: beeware/.github/.github/workflows/pre-commit-update.yml@main
+    secrets: inherit
+    with:
+      pre-commit-source: pre-commit
+      create-changenote: false

.github/workflows/translate.yml

@@ -0,0 +1,73 @@
+name: Update Translations
+on:
+  push:
+    branches:
+      main
+
+# Cancel active CI runs for a PR before starting another run
+concurrency:
+  group: translate-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash  # https://github.com/beeware/briefcase/pull/912
+
+env:
+  FORCE_COLOR: "1"
+
+jobs:
+  update-translations:
+    name: Update Translations
+    if: github.actor != 'brutusthebee'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4.2.2
+        with:
+          fetch-depth: 1
+          token: ${{ secrets.BRUTUS_PAT_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5.6.0
+        with:
+          python-version: "3.X"
+          cache: pip
+          cache-dependency-path: |
+            requirements.dev.txt
+            requirements.docs.txt
+            .pre-commit-config.yaml
+
+      - name: Update pip
+        run: python -m pip install -U pip
+
+      - name: Install tox
+        run: python -m pip install -r requirements.dev.txt
+
+      - name: Configure git
+        run: |
+          git config --local user.email "$(git log --pretty='%ae' -1)"
+          git config --local user.name "brutusthebee[bot]"
+
+      - name: Regenerate PO files
+        run: |
+          tox -e docs-translate
+
+      - name: Update Needed?
+        id: updated
+        run: |
+          if [[ $(git status --porcelain) ]]; then
+            echo "updated=true" >> ${GITHUB_OUTPUT}
+          else
+            echo "updated=false" >> ${GITHUB_OUTPUT}
+          fi
+
+      - name: Commit updated translations
+        if: steps.updated.outputs.updated == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          # Commit the updated PO files.
+          git add docs/locales
+          git commit -m "Update translations to $(git rev-parse --short HEAD)."
+          git push origin

.gitignore

@@ -1,3 +1,6 @@
+# MkDocs
+_build
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]
@@ -182,9 +185,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

.pyspelling.yml

@@ -14,7 +14,6 @@ matrix:
       - markdown.extensions.attr_list
       - pymdownx.superfences
       - pymdownx.blocks.admonition
-      - pymdownx.caret
       - pymdownx.blocks.caption
       - pymdownx.blocks.tab
   - pyspelling.filters.html:

README.md

@@ -1,2 +1,65 @@
-# beeware-docs-tools
-Tools for building BeeWare's documentation with a common theme and translations
+# BeeWare Docs Tools
+
+Tools for building BeeWare's documentation with a common theme and translations.
+
+## Adding a new language
+
+Weblate is able to generate a new language, however, adding a new language
+also requires a few changes to the documentation repository.
+
+Once a new language is generated, you'll need to add a new
+`mkdocs.<language-code>.yml` file and update the `tox.ini` file.
+
+The following example outlines how you would go about adding German to
+this repo. The concepts are the same for any language in any of the docs
+repos.
+
+### The new MkDocs configuration file
+
+The first thing to do is create a new file named `mkdocs.de.yml` in the
+`docs` directory, with the following content:
+
+```yaml
+INHERIT: config.yml
+site_name: BeeWare Demo zu Docs Tools
+site_url: https://tutorial.beeware.org/de
+docs_dir: de
+
+theme:
+  language: de
+
+extra:
+  translation_type: machine
+```
+
+Here's what is going on in this file:
+
+* This file inherits the configuration content from `config.yml`.
+* The `site_name` value is translated.
+* The `site_url` value is the project site URL, followed by the language
+  code.
+* The `docs_dir` should be the language code.
+* The `theme: language:` value should be the language code, as specified by the
+  MkDocs Material theme. The list can be found
+  [here](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/).
+  For most languages, this will be the same as the `docs_dir` language code; but
+  for some (in particular languages with locale variants like `zh_CN`), there are
+  differences.
+* The `extra: translation_type:` should be `machine` until the translation reaches
+  100% for the first time, at which point it should be `human`. It will revert to
+  `machine` from `human` if it regresses to below 90%.
+
+### The update to `tox.ini`
+
+You'll need to make several changes to this file.
+
+You'll need to add the following:
+
+* The language code environment flag to the header line which begins `[testenv:docs`,
+  preceded by a `-`, with no spaces included.
+* The language code exclusion to the first command, which begins with `!lint`,
+  preceded by `-!`, with no spaces included.
+* The language code to the end of the second line beginning with `translate :`.
+* The language code to the end of the line beginning with `all :`.
+* A new line at the end that matches the other language-specific lines with the
+  new language code.

docs/config.yml

@@ -26,6 +26,7 @@ theme:
   name: material
   language: en
   logo: assets/images/brutus-256.png
+  favicon: assets/images/brutus-256.png
   features:
     - content.tabs.link
     - toc.follow
@@ -34,7 +35,7 @@ theme:
     - search.suggest
     - search.highlight
     - search.share
-  # custom_dir: overrides
+  custom_dir: overrides
   palette:
     # Palette toggle for automatic mode
     - media: "(prefers-color-scheme)"
@@ -57,11 +58,9 @@ theme:
         name: Switch to system preference
 
 markdown_extensions:
-  pymdownx.highlight:
-    anchor_linenums: true
+  pymdownx.highlight: {}
   pymdownx.superfences: {}
   pymdownx.blocks.admonition: {}
-  pymdownx.caret: {}
   pymdownx.blocks.caption: {}
   pymdownx.blocks.tab:
     alternate_style: true

docs/en/SUMMARY.md

@@ -0,0 +1,4 @@
+- BeeWare Docs Tools Demo Section One
+    - [BeeWare Docs Tools Demo Section One](section_one/index.md)
+    - [Section One - Page Two](section_one/page_two.md)
+- [Section Two](section_two/index.md)

docs/en/index.md

@@ -1 +1,157 @@
-# BeeWare Test Page
+# BeeWare Docs Tools Demo
+
+## Theme checklist
+
+Things to manually check:
+
+### Titlebar
+
+A medium-gray titlebar is on the page. This the theme template
+has been applied.
+
+### Header and logo icons
+
+The header icon top-left has been rendered. This confirms the template
+can reference external resources.
+
+The logo icon in the left sidebar has been rendered. This confirms the
+sidebar will render properly on the target sites.
+
+### Heading font
+
+Headings are rendered in Cutive. This confirms the BeeWare custom CSS
+theme has been applied.
+
+### Inline Code
+
+Inline code is rendered in the same color as the surrounding font. This
+confirms that the theme has not caused any undesired changes.
+
+This is text with `inline code` here and `inline code` here.
+
+### Tabbed Content Code
+
+Code is in a contrasting color to the background. Copy button should
+copy only the commands; the prompt should not be included.
+
+This confirms that the theme has not caused any undesired changes,
+as well as whether the copy button is working as expected.
+
+/// tab | macOS
+
+``` console
+$ git clone https://github.com/beeware/beeware-theme.git
+```
+
+///
+
+/// tab | Linux
+
+``` console
+$ git clone https://github.com/beeware/beeware-theme.git
+```
+
+///
+
+/// tab | Windows
+
+``` doscon
+C:\...>git clone https://github.com/beeware/beeware-theme.git
+```
+
+///
+
+### Code copy button behavior
+
+The copy button on the following codeblock should result in `from pathlib
+import Path` being copied to the clipboard.
+
+```python
+from pathlib import Path
+```
+
+The copy button on the following codeblock should result in `ls
+beeware-docs-tools` being copied to the clipboard. The shell prompt and
+the output should not be included.
+
+```console
+(venv) $ ls beeware-docs-tools
+_build			locales			requirements.dev.txt	tox.ini
+docs			pyproject.toml		requirements.docs.txt
+LICENSE			README.md		src
+```
+
+### Sidebar links
+
+Sidebar links exist, and point to the `beeware-docs-tools` repo. This
+confirms that the sidebar content has been loaded, and the `project-name`
+has been set in the MkDocs configuration file.
+
+### Link colors
+
+This link to [the main BeeWare website](https://beeware.org) should be blue
+in *both* light mode and dark mode.
+
+The links in the left and right sidebars should also be blue in both modes.
+
+When scrolling down the page, the active header link in the right sidebar
+should be light blue in dark mode, and darker blue in light mode.
+
+### Translation Admonition
+
+The English-language version of this document should show the "Translations
+are available" admonition below. The French translation should show the "This is
+a machine translation!" admonition. The German translation should show the
+"This is a translation!" admonition for human translations.
+
+{% if config.extra.translation_type == "original" %}
+
+/// admonition | Translations are available
+
+If you're not comfortable with English, translations of the Docs Tools
+are available in Français and Deutsch.
+
+///
+
+{% endif %}
+
+{% if config.extra.translation_type == "machine" %}
+
+/// admonition | This is a machine translation!
+
+This version of the tutorial has been generated by machine translation.
+We know this isn't ideal, but we felt that a bad translation was better
+than no translation at all.
+
+///
+
+{% endif %}
+
+{% if config.extra.translation_type == "human" %}
+
+/// admonition | This is a translation!
+
+This document is a translation of the English version. The translation
+has been reviewed by humans, but newer sections may be generated by
+machine translation, or not translated at all.
+
+///
+
+{% endif %}
+
+### Custom 404 page
+
+Add `nopage` to the end of the URL in your browser to verify the 404
+page contains two flying bees, and the text "Brutus can't find what
+you're looking for" below.
+
+*MkDocs builds fail with unrecognized internal links, so you need to
+manually verify this check by modifying the URL in your browser.*
+
+### Next Checks
+
+The following link should take you to BeeWare Docs Tools Demo Section
+One. It is included to verify cross-page linking.
+
+Navigate to [BeeWare Docs Tools Demo Section One](section_one/index.md) for the
+next checks.