Contribution guide consolidation

.pre-commit-config.yaml

@@ -15,8 +15,9 @@ repos:
       - id: ruff-check
         args: [ --fix ]
       - id: ruff-format
-  - repo: https://github.com/rvben/rumdl-pre-commit
-    rev: v0.0.170
-    hooks:
-      - id: rumdl
-        args: [--force-exclude]
+# TODO: Reenable for final
+#  - repo: https://github.com/rvben/rumdl-pre-commit
+#    rev: v0.0.170
+#    hooks:
+#      - id: rumdl
+#        args: []

.pyspelling.yml

@@ -34,6 +34,14 @@ matrix:
         - open: '{%'
           content: '[\d\D]*'
           close: '%}'
+        # Ignores the Jinja variables and their contents
+        - open: '{{'
+          content: '[\d\D]*'
+          close: '}}'
+        # Ignores the autorefs link targets
+        - open: '\]\['
+          content: '[\d\D]*'
+          close: '\]'
         # Ignore the mkdocstrings calls
         - open: ':::'
           content: '[\d\D]*'

.rumdl.toml

@@ -5,9 +5,22 @@ 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",]
+# MD014: Force commands in codeblocks to show output
+disable = ["MD014",]
+
+[per-file-ignores]
+# MD002: First heading should be level 1, found level 2; title will be included in the target page
+# MD034: URL without angle brackets or link formatting; triggers on URLs with Jinja variable included
+# MD041: First line in file should be level 1 heading; title will be included in the target page
+"src/beeware_docs_tools/shared_content/en/*_base.md" = ["MD002", "MD034", "MD041",]
+
+[MD013]  # Line length
+line_length = 999999  # Force reflow to paragraph content to remove linebreaks
+reflow = true
+reflow_mode = "normalize"
+
+[MD026]  # Remove punctuation at the end of headings
+punctuation = ",;:"
 
 [MD033]  # No inline HTML
 allowed_elements = ["nospell",]  # pyspelling inline disable tag

README.md

@@ -4,20 +4,15 @@ 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.
+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.
+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 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:
+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
@@ -36,30 +31,19 @@ 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 `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 `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 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.
+* A new line at the end that matches the other language-specific lines with the new language code.

docs/config.yml

@@ -2,6 +2,7 @@ copyright: © Russell Keith-Magee
 
 not_in_nav: |
   /index.md
+  /about/releases.md
 
 validation:
   omitted_files: warn
@@ -12,6 +13,14 @@ validation:
 extra:
   project_name: beeware-docs-tools
   package_name: beeware-docs-tools
+  formal_name: "BeeWare Docs Tools"
+  website: true  # true shows beeware.org-specific content, false shows project content. Default: false.
+  min_python_version: "3.10"  # The oldest supported Python version
+  min_python_version_tag: "310"  # The tag version of the minimum python version
+  recent_python_version: "3.13"  # The newest Python version known to work on all platforms
+  translated: false  # true hides content related to building translations. Default: false.
+  hide_coverage: false  # true hides content related to code coverage. Default: false.
+  macos_only: false  # true hides tabbed content, and displays only macOS instructions. Default: false.
   alternate:
     - name: English
       link: /en/
@@ -89,7 +98,8 @@ plugins:
   autorefs: {}
   literate-nav:
     nav_file: SUMMARY.md
-  macros: {}
+  macros:
+    include_dir: docs
   mkdocstrings:
     default_handler: python
     handlers:

docs/en/SUMMARY.md

@@ -7,3 +7,8 @@
 - Shared content test bed
     - [Shared content test bed](content_test_bed/index.md)
     - [Style guide](content_test_bed/style_guide_include.md)
+    - [The lifecycle of a new feature base guide](content_test_bed/how-to/feature_proposal_base_include.md)
+    - [Code contribution base guide](content_test_bed/how-to/contribute/code_contribution_base_include.md)
+    - [Docs contribution base guide](content_test_bed/how-to/contribute/docs_contribution_base_include.md)
+    - [Contributing base guide](content_test_bed/how-to/contribute/index.md)
+    - [The Contribution Process](content_test_bed/how-to/contribute/contribution_process_base_include.md)

docs/en/about/releases.md

@@ -0,0 +1,3 @@
+# Place-holder file
+
+This file is included purely to satisfy the link in the `code_contribution_base.md` file. It is excluded from nav.

docs/en/content_test_bed/how-to/contribute/code_contribution_base_include.md

@@ -0,0 +1,7 @@
+# Contributing code to {{ formal_name }}  { #contribute-code }
+
+{% extends "code_contribution_base.md" %}
+
+{% block contribution_topics_new_feature %}
+Here is where you would add project-specific feature topics.
+{% endblock %}

docs/en/content_test_bed/how-to/contribute/contribution_process_base_include.md

@@ -0,0 +1,5 @@
+# The Contribution Process
+
+TODO: Update title
+
+{% extends "contribution_process_base.md" %}

docs/en/content_test_bed/how-to/contribute/docs_contribution_base_include.md

@@ -0,0 +1,3 @@
+# Contributing documentation to {{ formal_name }} { #contribute-docs }
+
+{% extends "docs_contribution_base.md" %}

docs/en/content_test_bed/how-to/contribute/index.md

@@ -0,0 +1,3 @@
+# Contributing to {{ formal_name }}
+
+{% extends "contributing_base.md" %}

docs/en/content_test_bed/how-to/feature_proposal_base_include.md

@@ -0,0 +1,3 @@
+# The lifecycle of a new feature
+
+{% extends "feature_proposal_base.md" %}

docs/en/content_test_bed/index.md

@@ -7,10 +7,10 @@ If you are updating existing content, the following steps are not necessary. You
 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`.
+   * 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`.
+   * 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)`.
+   * 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/section_one/index.md

@@ -16,10 +16,14 @@ The following section should have only a header, and a paragraph with inline cod
 
 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.
 
+<!-- rumdl-disable MD013 MD034 -->
+
 -8<-
 https://raw.githubusercontent.com/beeware/beeware-docs-tools/refs/heads/main/docs/include_content.md:remote-content
 -8<-
 
+<!-- rumdl-enable MD013 MD034 -->
+
 ## Footer navigation
 
 Navigate to *Section One - Page Two* for the final check.

docs/spelling_wordlist

@@ -1,22 +1,43 @@
+accelerometer
+accelerometers
 artefact
 artefacts
+backend
+backends
 Backticks
 backticks
 BeeWare
 BeeWare's
+codebase
 codeblock
 codeblocks
 Cutive
 Deutsch
+Dev
+dev
+Diataxis
 Français
+GTK
+HTTPS
 Jinja
+Jinja's
+lifecycle
+linters
 macOS
 MkDocs
 Namespaces
 namespace
+nav
+pre
+PR
+PRs
+PyScript
+Pygame
+pytest
 repo
 repos
 reStructuredText
+rumdl
 scrollable
 scrollbar
 subdirectories
@@ -25,6 +46,10 @@ symlinked
 symlinking
 Titlebar
 titlebar
+Triaging
+tvOS
 verbing
+visionOS
+watchOS
 Weblate
 webpage

src/beeware_docs_tools/md_tempdir.py

@@ -34,6 +34,7 @@ def save_config(project_path, temp_md_path, config_file, language="en"):
 
     base_path.append(str(shared_content_path))
     config_file["markdown_extensions"]["pymdownx.snippets"]["base_path"] = base_path
+    config_file["plugins"]["macros"]["include_dir"] = str(shared_content_path)
 
     with (temp_md_path / "config.yml").open("w", encoding="utf-8") as config_temp:
         yaml.dump(config_file, config_temp)

src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css

@@ -322,6 +322,11 @@
     box-shadow: unset;
 }
 
+/* Force admonitions to render at the same font size as the rest of the content */
+.md-typeset .admonition {
+    font-size: unset;
+}
+
 /* Sidebar title and GitHub links font and color */
 .md-nav__title {
     font-family: 'Cutive', serif;