Config updates for website migration compatibility. (#2665)

Author: kattni

changes/2665.misc.md

@@ -0,0 +1 @@
+ Documentation build configuration is now updated to work with the updated tooling.

docs/config.yml

@@ -33,6 +33,7 @@ extra:
   "ci_tested": ●
   "maintainer_tested": ○
   "not_tested": △
+  generator: false
 
 extra_css:
   - stylesheets/briefcase.css
@@ -45,6 +46,8 @@ theme:
   features:
     - content.tabs.link
     - toc.follow
+    - navigation.tabs
+    - navigation.tabs.sticky
     - navigation.indexes
     - navigation.footer
     - search.suggest
@@ -73,21 +76,58 @@ theme:
         name: Switch to system preference
 
 markdown_extensions:
+  # PyMdown Extensions
   pymdownx.highlight: {}
   pymdownx.superfences: {}
-  pymdownx.blocks.admonition: {}
   pymdownx.blocks.caption: {}
-  pymdownx.details: {}
+  pymdownx.blocks.admonition:  # Enables admonitions.
+    types:
+      - note
+      - abstract
+      - info
+      - tip
+      - success
+      - question
+      - warning
+      - failure
+      - danger
+      - bug
+      - example
+      - quote
+  pymdownx.blocks.details:  # Enables collapsible content.
+    types:
+      - {name: details-note, class: note}
+      - {name: details-abstract, class: abstract}
+      - {name: details-info, class: info}
+      - {name: details-tip, class: tip}
+      - {name: details-success, class: success}
+      - {name: details-question, class: question}
+      - {name: details-warning, class: warning}
+      - {name: details-failure, class: failure}
+      - {name: details-danger, class: danger}
+      - {name: details-bug, class: bug}
+      - {name: details-example, class: example}
+      - {name: details-quote, class: quote}
   pymdownx.blocks.tab:
     alternate_style: true
+  pymdownx.magiclink:  # Among other things, enables GitHub shorthand references.
+    provider: "github"
+    user: "beeware"
+    repo: "toga"
+    repo_url_shortener: true
+    repo_url_shorthand: true
+    normalize_issue_symbols: true
   pymdownx.snippets:
     base_path: ["docs/en"]
     url_download: true
     check_paths: true
+  # Python Markdown Extensions
+  attr_list: {}
+  smarty:  # Enables easy em and en dashes.
+    smart_quotes: false
   toc:
     permalink: true
     title: On this page
-  attr_list: {}
 
 plugins:
   search: {}

docs/mkdocs.en.yml

@@ -5,3 +5,6 @@ docs_dir: en
 
 theme:
   language: en
+
+extra:
+  header: {}

pyproject.toml

@@ -108,7 +108,7 @@ setuptools-scm = [
 ]
 
 towncrier = [
-    "towncrier==25.8.0",
+    "towncrier == 25.8.0",
 ]
 
 tox-uv = [

tox.ini

@@ -98,6 +98,6 @@ commands =
     !lint-!all-!live-!en : build_md_translations {posargs} en
     lint : pyspelling
     lint : markdown-checker --dir {[docs]docs_dir} --func check_broken_urls --skip-domains=https://www.firegiant.com,https://flathub.org,https://wunjo.online,https://www.x.org
-    live : live_serve_en {posargs}
+    live : live_serve_en {posargs} --port=8039
     all : build_md_translations {posargs} en
     en : build_md_translations {posargs} en