Add style guide, rework translation tooling, shift to single translation file. (#30)

Author: kattni

.pre-commit-config.yaml

@@ -15,3 +15,8 @@ repos:
       - id: ruff-check
         args: [ --fix ]
       - id: ruff-format
+  - repo: https://github.com/rvben/rumdl-pre-commit
+    rev: v0.0.136
+    hooks:
+      - id: rumdl
+        args: [--force-exclude]

.pyspelling.yml

@@ -5,7 +5,8 @@ matrix:
     - docs/spelling_wordlist
     output: _build/dictionary/python.dic
   sources:
-  - '**/*.md'
+  - 'docs/**/*.md'
+  - 'src/**/*.md'
   pipeline:
   - pyspelling.filters.markdown:
       markdown_extensions:

.rumdl.toml

@@ -0,0 +1,13 @@
+[global]
+flavor = "mkdocs"
+include = ["**/*.md"]
+exclude = ["docs/en/content_test_bed/*_include.md", "docs/en/SUMMARY.md"]
+respect-gitignore = true
+
+# Disable rules:
+# MD013: Enforces line length
+# MD014: Forces commands in codeblocks to show output
+disable = ["MD013", "MD014",]
+
+[MD033]  # No inline HTML
+allowed_elements = ["nospell",]  # pyspelling inline disable tag

docs/config.yml

@@ -2,6 +2,7 @@ copyright: © Russell Keith-Magee
 
 not_in_nav: |
   /index.md
+  shared_content/*.md
 
 validation:
   omitted_files: warn

docs/en/SUMMARY.md

@@ -4,3 +4,6 @@
 - [Section two](section_two/index.md)
 - [Section three](section_three/index.md)
     - ./section_three/*
+- Shared content test bed
+    - [Shared content test bed](content_test_bed/index.md)
+    - [Style guide](content_test_bed/style_guide_include.md)

docs/en/content_test_bed/index.md

@@ -0,0 +1,16 @@
+# Shared content test bed
+
+This section is included for the purposes of verifying the shared content provided from this repo for use in the rest of the BeeWare documentation. "Shared content" refers to documents or sections of documents that are common to multiple other repos. They are stored here for inclusion across those repos. This means there is a single source when updates are required, and that change will populate across all repos using that shared content.
+
+If you are updating existing content, the following steps are not necessary. You can simply build the test site, and see your updates rendered.
+
+If you are creating a new shared documentation file in the `shared-content` directory, complete the following:
+
+1. Create a file in the `content_test_bed` that is the same filename as your new content file, with "_include" appended to the end.
+      * For `style_guide.md`, you would add `style_guide_include.md`.
+2. Using the Snippets syntax, add the filename to `filename_include.md`. The Snippets syntax for including content is `-8<- "filename.md"`.
+      * For `style_guide.md`, you would add `-8<- "style_guide.md"` to `style_guide_include.md`.
+3. Update the `Shared content test bed` section in `/docs/SUMMARY.md` to include the new `_include` file and path, at the same indentation level as the other items in that section.
+      * For `style_guide_include.md`, you would add `- [Style guide](content_test_bed/style_guide_include.md)`.
+
+Once these steps are completed, you can build the test site and view your new documentation rendered.

docs/en/content_test_bed/style_guide_include.md

@@ -0,0 +1 @@
+-8<- "style_guide.md"

docs/en/index.md

@@ -2,49 +2,37 @@
 
 ## Theme checklist
 
-This demo is designed to test the various features of the BeeWare
-MkDocs Material theme overrides. Please read through and verify
-that everything listed on this and the following pages is present
-and functioning as detailed in the description.
+This demo is designed to test the various features of the BeeWare MkDocs Material theme overrides. Please read through and verify that everything listed on this and the following pages is present and functioning as detailed in the description.
 
 ## Titlebar
 
-A medium-gray titlebar is on the page. This the theme template
-has been applied.
+A medium-gray titlebar is on the page. This the theme template has been applied.
 
 ## Header icon
 
-The header icon top-left has been rendered. This confirms the template
-can reference external resources.
+The header icon top-left has been rendered. This confirms the template can reference external resources.
 
 ## Homepage sidebar icon
 
-The logo icon in the left sidebar has been rendered. The logo should be
-the width of, and of equal height to, the sidebar. The site title should
-be rendered below it in slightly larger font than the rest of the
-sidebar, with the version number below it in smaller font.
+The logo icon in the left sidebar has been rendered. The logo should be the width of, and of equal height to, the sidebar. The site title should be rendered below it in slightly larger font than the rest of the sidebar, with the version number below it in smaller font.
 
 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.
+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.
+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.
+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.
+This confirms that the theme has not caused any undesired changes, as well as whether the copy button is working as expected.
 
 /// tab | macOS
 
@@ -72,16 +60,13 @@ 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.
+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.
+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
@@ -92,37 +77,25 @@ 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, and the version number is
-computed and added.
+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, and the version number is computed and added.
 
 ## Link colors
 
-This link to [the main BeeWare website](https://beeware.org) should be blue
-in *both* light mode and dark mode.
+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.
+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.
+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](https://beeware-docs-tools.readthedocs.io/fr/latest/)
-and
-[Deutsch](https://beeware-docs-tools.readthedocs.io/de/latest/).
+If you're not comfortable with English, translations of the Docs Tools are available in [Français](https://beeware-docs-tools.readthedocs.io/fr/latest/) and [Deutsch](https://beeware-docs-tools.readthedocs.io/de/latest/).
 
 ///
 
@@ -132,9 +105,7 @@ and
 
 /// 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.
+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.
 
 ///
 
@@ -144,27 +115,20 @@ than no translation at all.
 
 /// 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.
+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.
+Add `nopage` to the end of the URL in your browser to verify the 404 page exists, and includes the text "Brutus can't find what you're looking for". The current 404 page does not always render the images due to an issue with MkDocs.
 
-*MkDocs builds fail with unrecognized internal links, so you need to
-manually verify this check by modifying the URL in your browser.*
+*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.
+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.
+Navigate to [BeeWare Docs Tools Demo Section One](section_one/index.md) for the next checks.

docs/en/section_one/index.md

@@ -2,26 +2,19 @@
 
 ## Non-homepage sidebar logo
 
-The logo icon in the left sidebar should be small on all pages other than the
-homepage. The site title and version number should be rendered next to it with
-the site title in slightly larger font, and the version number in smaller font.
+The logo icon in the left sidebar should be small on all pages other than the homepage. The site title and version number should be rendered next to it with the site title in slightly larger font, and the version number in smaller font.
 
 This verifies that the theme is being properly applied.
 
 ## Include external markdown from a local file
 
-The following section should have only a header, and a paragraph with inline code
-followed by a code block. There should be no text between the code block and the
-next header. This verifies that the external include extension is working with
-local files.
+The following section should have only a header, and a paragraph with inline code followed by a code block. There should be no text between the code block and the next header. This verifies that the external include extension is working with local files.
 
 -8<- "include_content.md:local-content"
 
 ## Include external markdown from a URL
 
-The following section should have only a header, some text and a Markdown list.
-This verifies that the external include extension is working, and that
-`url_download` is enabled.
+The following section should have only a header, some text and a Markdown list. This verifies that the external include extension is working, and that `url_download` is enabled.
 
 -8<-
 https://raw.githubusercontent.com/beeware/beeware-docs-tools/refs/heads/main/docs/include_content.md:remote-content

docs/en/section_one/page_two.md

@@ -1,17 +1,11 @@
 # BeeWare Docs Tools Demo section one: page two
 
-### Footer and navigation links
+## Footer and navigation links
 
-Navigation should render at the bottom of the page; "BeeWare Docs Tools Demo
-Section One" should be on the left, "Section Two" should be on the right.
-The footer should be below the navigation links. This confirms the theme
-configuration has been applied.
+Navigation should render at the bottom of the page; "BeeWare Docs Tools Demo Section One" should be on the left, "Section Two" should be on the right. The footer should be below the navigation links. This confirms the theme configuration has been applied.
 
-### Class reference documentation
+## Class reference documentation
 
-The following should show the reference documentation for the `DocsTest`
-class, located in `docs_test.py`, in the `src/beeware_docs_tools`
-directory. This verifies that the source code directory symlinking is
-working properly.
+The following should show the reference documentation for the `DocsTest` class, located in `docs_test.py`, in the `src/beeware_docs_tools` directory. This verifies that the source code directory symlinking is working properly.
 
 ::: beeware_docs_tools.docs_test.DocsTest