Guide tweaks needed for Toga (#137)

Co-authored-by: Russell Keith-Magee <[email protected]>

Author: kattni

docs/config.yml

@@ -94,6 +94,7 @@ markdown_extensions:
     permalink: true
     title: On this page
   attr_list: {}
+  admonition: {}  # Enabled for all admonition types EXCEPT note and admonition (which defaults to note)
 
 plugins:
   search: {}

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

@@ -10,7 +10,7 @@ Your pull request may require additional content, such as a [change note](change
 
 {% else %}
 
-As part of submitting a pull request, you'll need to include a [change note](change_note.md) before it can be [the reviewed](../next/pr_review.md).
+As part of submitting a pull request, you'll need to include a [change note](change_note.md) before it can be [reviewed](../next/pr_review.md).
 
 {% endif %}
 

src/beeware_docs_tools/shared_content/en/contribute/how/build_docs.md

@@ -11,14 +11,13 @@ You **must** have a Python {{ docs_python_version }} interpreter installed and a
 
 To support rapid editing of documentation, {{ formal_name }} has a "live preview" mode.
 
-/// admonition | The live preview will build with warnings!
-    type: warning
+<!-- rumdl-disable MD031 MD046 -->
+!!! warning "The live preview will build with warnings!"
 
-The live serve is available for iterating on your documentation updates. While you're in the process of updating things, you may introduce a markup issue. Issues considered a `WARNING` will cause a standard build to fail, however, the live serve is set up to indicate warnings in the console output, while continuing to build. This allows you to iterate without needing to restart the live preview.
+    The live serve is available for iterating on your documentation updates. While you're in the process of updating things, you may introduce a markup issue. Issues considered a `WARNING` will cause a standard build to fail, however, the live serve is set up to indicate warnings in the console output, while continuing to build. This allows you to iterate without needing to restart the live preview.
 
-A `WARNING` is different from an `ERROR`. If you introduce an issue that is considered an `ERROR`, the live serve will fail, and require a restart. It will not start up again until the `WARNING` issue is resolved.
-
-///
+    A `WARNING` is different from an `ERROR`. If you introduce an issue that is considered an `ERROR`, the live serve will fail, and require a restart. It will not start up again until the `WARNING` issue is resolved.
+<!-- rumdl-enable MD031 MD046 -->
 
 To start the live server:
 

src/beeware_docs_tools/shared_content/en/contribute/how/dev_environment.md

@@ -23,7 +23,6 @@ If you have more than one version of Python installed, you may need to replace `
 We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on macOS often lag usually aren't available for recently released stable Python versions.
 
 {% block prerequisites_macos %}
-
 {% endblock %}
 
 {% if not config.extra.macos_only %}
@@ -45,7 +44,6 @@ If you have more than one version of Python installed, you may need to replace `
 We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on Linux often lag usually aren't available for recently released stable Python versions.
 
 {% block prerequisites_linux %}
-
 {% endblock %}
 
 ///
@@ -65,7 +63,6 @@ If you have more than one version of Python installed, you may need to replace t
 We recommend avoiding recently released version of Python (i.e., versions that have a ".0" or ".1" micro version number, like e.g., 3.14.0). This is because the tools needed to support Python on Windows often lag usually aren't available for recently released stable Python versions.
 
 {% block prerequisites_windows %}
-
 {% endblock %}
 
 ///

src/beeware_docs_tools/shared_content/en/contribute/how/propose_feature.md

@@ -29,5 +29,4 @@ Once the discussion has reached a consensus on the form of a feature, you can cr
 You don't have to implement your feature proposal yourself; you can open an issue with the details of what you're proposing. However, simply posting the issue doesn't mean it's going to be implemented for you. You'll need to wait for it to potentially get picked up by someone else interested in the same feature, whether that means another community member or the core team; however this is not guaranteed to happen. If you want the guarantee implementation, you'll need to implement it yourself, or pay someone else to implement it for you.
 
 {% block end_matter %}
-
 {% endblock %}

src/beeware_docs_tools/shared_content/en/contribute/how/submit_pr.md

@@ -239,12 +239,11 @@ If you've previously pushed the current branch to GitHub, you won't receive the
 
 Any of these options will enable you to create your new pull request.
 
-/// admonition | The GitHub CLI: `gh`
-    type: info
+<!-- rumdl-disable MD031 -->
+!!! info "The GitHub CLI: `gh`"
 
-GitHub provides the [GitHub CLI](https://cli.github.com/), which gives you access to many of the features of GitHub from your terminal, through the `gh` command. The [GitHub CLI documentation](https://cli.github.com/manual/) covers all the features.
-
-///
+    GitHub provides the [GitHub CLI](https://cli.github.com/), which gives you access to many of the features of GitHub from your terminal, through the `gh` command. The [GitHub CLI documentation](https://cli.github.com/manual/) covers all the features.
+<!-- rumdl-enable MD031 -->
 
 ### Pull request content
 
@@ -281,5 +280,4 @@ We have limited CI resources. It is important to understand that every time you
 The process of submitting your PR is not done until it's passing CI, or you can provide an explanation for why it's not.
 
 {% block end_matter %}
-
 {% endblock %}

src/beeware_docs_tools/shared_content/en/contribute/how/write_code.md

@@ -6,7 +6,7 @@ Fixing a bug or implementing a feature will require you to write some new code.
 
 We have a [code style guide](../style/code_style_guide.md) that outlines our guidelines for writing code for BeeWare.
 
-#### Test-driven development
+### Test-driven development
 
 A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.
 
@@ -78,12 +78,11 @@ The full test suite can take a while to run. You can speed it up considerably by
 
 {% if not config.extra.hide_coverage %}
 
-As with the full test suite, and the core, this should report [100% test coverage][code-coverage].
+In addition to the tests passing, this should report [100% test coverage][code-coverage].
 
 {% endif %}
 
 {% block testing_running_additional %}
-
 {% endblock %}
 
 ### Running test variations
@@ -165,7 +164,6 @@ By default, `tox` will run all tests in the unit test suite. When you're develop
 {% endif %}
 
 {% block testing_subset_additional %}
-
 {% endblock %}
 
 {% if not config.extra.hide_coverage %}
@@ -395,7 +393,6 @@ A HTML coverage report can be generated by appending `-html` to any of the cover
 {% endif %}
 
 {% block testing_additional %}
-
 {% endblock %}
 
 ### It's not just about writing tests!

src/beeware_docs_tools/shared_content/en/contribute/next/pr_review.md

@@ -19,14 +19,11 @@ Congratulations! You've just made a contribution to {{ formal_name }}!
 
 After submitting your pull request, you'll need to wait for a review of your contribution. There are two sides to the review process: providing a review and receiving a review.
 
-/// admonition | Review expectations
-    type: info
+!!! info "Review expectations"
 
-You should expect anyone reviewing your submissions to follow these guidelines, including reviews from members of the core team. You should also follow these guidelines when you are reviewing submissions from others.
+    You should expect anyone reviewing your submissions to follow these guidelines, including reviews from members of the core team. You should also follow these guidelines when you are reviewing submissions from others.
 
-If you feel your reviewer is straying from these expectations, and you feel comfortable raising the issue yourself on the pull request, you can do so. If you don't feel comfortable, please reach out to the [BeeWare Code of Conduct Response Team](https://beeware.org/bee/coc). We will review your report, and follow up with your reviewer. The follow-up will reflect the reported action; a minor transgression may result in a discussion, whereas a major violation may result in something more serious.
-
-///
+    If you feel your reviewer is straying from these expectations, and you feel comfortable raising the issue yourself on the pull request, you can do so. If you don't feel comfortable, please reach out to the [BeeWare Code of Conduct Response Team](https://beeware.org/bee/coc). We will review your report, and follow up with your reviewer. The follow-up will reflect the reported action; a minor transgression may result in a discussion, whereas a major violation may result in something more serious.
 
 ## Providing a review
 
@@ -62,25 +59,19 @@ If the initial review reveals a significant number of problems, the first review
 
 Your reviewer will post comments to your pull request. These comments can be general, on a specific file, or on a specific line or lines of code. They will sometimes include directly suggested changes that you can apply to your pull request through the GitHub UI. Typically, they will be questions, requests for clarification, or guidance on updates.
 
-/// admonition | Marking a conversation as resolved
-    type: info
-
-During the discussion part of the feedback process, you should never mark a conversation started by your reviewer as "resolved". Marking the conversation as resolved is the responsibility of the reviewer. It's up to them to determine whether the identified problem has been solved.
+!!! info "Marking a conversation as resolved"
 
-///
+    During the discussion part of the feedback process, you should never mark a conversation started by your reviewer as "resolved". Marking the conversation as resolved is the responsibility of the reviewer. It's up to them to determine whether the identified problem has been solved.
 
 If the review reveals a systematic problem (e.g., a naming inconsistency that exists in the code), the reviewer may not highlight every instance of that problem. Instead, they may pick a couple of examples of the problem, and indicate that other instances should also be corrected. If a review highlights a problem in once place, and you think it might apply elsewhere, you should fix that problem wherever it occurs. If you're unsure, ask for clarification from your reviewer.
 
 #### Submit all requested changes
 
 Once you've worked through all the requested changes, you can push an update to your pull request. This will trigger a new CI run; once you have confirmed that CI is still passing, post a comment requesting an updated review and the core team will take another look at your pull request.
 
-/// admonition | Push, don't force or rebase
-    type: info
-
-When you're updating your pull request during a review, it is important to leave the commit history intact. It doesn't matter if there's a huge list of commits; they are all squashed when we merge the pull request. If you force push or rebase your pull request in the middle of a review, you may be removing important context needed by your reviewer.
+!!! info "Push, don't force or rebase"
 
-///
+    When you're updating your pull request during a review, it is important to leave the commit history intact. It doesn't matter if there's a huge list of commits; they are all squashed when we merge the pull request. If you force push or rebase your pull request in the middle of a review, you may be removing important context needed by your reviewer.
 
 #### Re-request a review
 

src/beeware_docs_tools/shared_content/en/contribute/style/code_style_guide.md

@@ -9,7 +9,6 @@ Keep in mind that the most important part of PEP 8 is [Section 0: A Foolish Cons
 We follow US spelling for API naming, variables, etc.
 
 {% block code_style %}
-
 {% endblock %}
 
 ### Things to avoid

src/beeware_docs_tools/shared_content/en/contribute/style/docs_style_guide.md

@@ -206,20 +206,19 @@ Note text here.
 Content below.
 ```
 
-When applying any of the other [supported admonition types](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types), you add a `type` directive below the title line, formatted as follows:
+When using any of the other [supported admonition types](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types), you'll use the following format. Ensure the admonition content is tabbed over four spaces, as follows:
 
+<!-- rumdl-disable MD031 -->
 ```markdown
 Content above.
 
-/// admonition | Info title
-    type: info
-
-Info text here.
+!!! info "Info title"
 
-///
+    Info text here.
 
 Content below.
 ```
+<!-- rumdl-disable MD031 -->
 
 Supported types include: abstract, info, tip, success, question, warning, failure, danger, bug, example, and quote.