Contribution guide consolidation (#94)

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: Russell Keith-Magee <[email protected]>
Co-authored-by: Brutus the Bee <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Charles Whittington <[email protected]>

Author: 5 people

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
         args: [ --fix ]
       - id: ruff-format
   - repo: https://github.com/rvben/rumdl-pre-commit
-    rev: v0.0.190
+    rev: v0.0.192
     hooks:
       - id: rumdl
-        args: [--force-exclude]
+        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

@@ -1,13 +1,29 @@
 [global]
 flavor = "mkdocs"
 include = ["**/*.md"]
-exclude = ["docs/en/content_test_bed/*_include.md", "docs/en/SUMMARY.md"]
+exclude = ["docs/en/SUMMARY.md", "comment.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/*.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
+
+[MD061]
+terms = ["TODO"]

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](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,15 @@ validation:
 extra:
   project_name: beeware-docs-tools
   package_name: beeware-docs-tools
+  formal_name: "BeeWare Docs Tools"
+  website: false  # 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
+  docs_python_version: "3.13"  # The version of Python required to build the documentation
+  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/
@@ -73,6 +83,7 @@ markdown_extensions:
   pymdownx.superfences: {}
   pymdownx.blocks.admonition: {}
   pymdownx.blocks.caption: {}
+  pymdownx.details: {}
   pymdownx.blocks.tab:
     alternate_style: true
   pymdownx.snippets:
@@ -86,10 +97,12 @@ markdown_extensions:
 
 plugins:
   search: {}
-  autorefs: {}
+  autorefs:
+    resolve_closest: true  # autorefs warns of the Usage headings begin duplicates without this - we will have to assign unique ids to all of them otherwise
   literate-nav:
     nav_file: SUMMARY.md
-  macros: {}
+  macros:
+    include_dir: {}
   mkdocstrings:
     default_handler: python
     handlers:

docs/en/SUMMARY.md

@@ -6,4 +6,36 @@
     - ./section_three/*
 - Shared content test bed
     - [Shared content test bed](content_test_bed/index.md)
-    - [Style guide](content_test_bed/style_guide_include.md)
+    - How-to guides
+        - Contribute
+            - [Contributing](content_test_bed/how-to/contribute/index.md)
+            - [First-time contributors](content_test_bed/how-to/contribute/first_time_contributors.md)
+            - What can I do?
+                - [Fix an issue](content_test_bed/how-to/contribute/what/fix_issue.md)
+                - [Implement a new feature](content_test_bed/how-to/contribute/what/implement_feature.md)
+                - [Write documentation](content_test_bed/how-to/contribute/what/write_docs.md)
+                - [Triage an issue](content_test_bed/how-to/contribute/what/triage.md)
+                - [Review a pull request](content_test_bed/how-to/contribute/what/review_pr.md)
+                - [Propose a new feature](content_test_bed/how-to/contribute/what/propose_feature.md)
+                - [Translate content](content_test_bed/how-to/contribute/what/translate.md)
+                - [Use the tools](content_test_bed/how-to/contribute/what/use_tools.md)
+            - How do I contribute?
+                - [Setting up a development environment](content_test_bed/how-to/contribute/how/dev_environment.md)
+                - [Reproducing an issue](content_test_bed/how-to/contribute/how/reproduce_issue.md)
+                - [Working from a branch](content_test_bed/how-to/contribute/how/branches.md)
+                - [Avoiding scope creep](content_test_bed/how-to/contribute/how/scope_creep.md)
+                - [Writing, running, and testing code](content_test_bed/how-to/contribute/how/write_code.md)
+                - [Building documentation](content_test_bed/how-to/contribute/how/build_docs.md)
+                - [Writing documentation](content_test_bed/how-to/contribute/how/write_docs.md)
+                - [Adding a change note](content_test_bed/how-to/contribute/how/change_note.md)
+                - [Submitting a pull request](content_test_bed/how-to/contribute/how/submit_pr.md)
+                - [Providing a review](content_test_bed/how-to/contribute/how/review_pr.md)
+                - [Submitting a new issue](content_test_bed/how-to/contribute/how/new_issue.md)
+                - [Proposing a new feature](content_test_bed/how-to/contribute/how/propose_feature.md)
+                - [Translating content](content_test_bed/how-to/contribute/how/translate.md)
+            - What happens next?
+                - [Pull request review process](content_test_bed/how-to/contribute/next/pr_review.md)
+                - [Release process](content_test_bed/how-to/contribute/next/release.md)
+            - Style guides
+                - [Code style guide](content_test_bed/how-to/contribute/style/code_style_guide.md)
+                - [Documentation style guide](content_test_bed/how-to/contribute/style/docs_style_guide.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/first_time_contributors.md

@@ -0,0 +1,3 @@
+# First-time contributors
+
+{% extends "contribute/first_time_contributors.md" %}

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

@@ -0,0 +1,3 @@
+# Work from a feature branch, not your `main` branch
+
+{% extends "contribute/how/branches.md" %}

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

@@ -0,0 +1,15 @@
+# Building documentation
+
+{% extends "contribute/how/build_docs.md" %}
+
+{% block front_matter %}
+
+Before you build the documentation, and have a [development environment](dev_environment.md) set up.
+
+{% endblock %}
+
+{% block end_matter %}
+
+Once you have successfully built the docs, you are ready to [write documentation](write_docs.md).
+
+{% endblock %}