Move Toga to MkDocs and Markdown

.github/workflows/ci.yml

@@ -33,17 +33,13 @@ jobs:
     name: Pre-commit checks
     uses: beeware/.github/.github/workflows/pre-commit-run.yml@main
     with:
-      # Although we only want to install the dev dependencies, we have to install the
-      # core, which means we need travertino as well.
-      pre-commit-source: "./travertino ./core[dev]"
+      pre-commit-source: "--group pre-commit"
 
   towncrier:
     name: Check towncrier
     uses: beeware/.github/.github/workflows/towncrier-run.yml@main
     with:
-      # Although we only want to install the dev dependencies, we have to install the
-      # core, which means we need travertino as well.
-      tox-source: "./travertino ./core[dev]"
+      tox-source: "--group tox-uv"
 
   package:
     name: Package Toga
@@ -108,11 +104,7 @@ jobs:
         allow-prereleases: true
 
     - name: Install Tox
-      uses: beeware/.github/.github/actions/install-requirement@main
-      with:
-        requirements: tox
-        extra: dev
-        project-root: core
+      run: python -m pip install --group tox-uv
 
     - name: Get Packages
       uses: actions/[email protected]
@@ -126,7 +118,7 @@ jobs:
         # The $(ls ...) shell expansion is done in the GitHub environment; the value of
         # TOGA_INSTALL_COMMAND will be a literal string without any shell expansions to
         # perform.
-        export TOGA_INSTALL_COMMAND="python -m pip install ../$(ls dist/toga_core-*.whl)[dev] ../$(ls dist/travertino-*.whl) ../$(ls dist/toga_dummy-*.whl)"
+        export TOGA_INSTALL_COMMAND="uv pip install ../$(ls dist/toga_core-*.whl) ../$(ls dist/travertino-*.whl) ../$(ls dist/toga_dummy-*.whl) --group dev"
         tox -e py-cov${{ matrix.tox-suffix }}
         tox -qe coverage$(tr -dc "0-9" <<< "${{ matrix.python-version }}")${{ matrix.tox-suffix }}
         mv ${{ matrix.package }}/.coverage ${{ matrix.package }}/.coverage.${{ matrix.platform }}.${{ matrix.python-version }}
@@ -165,11 +157,7 @@ jobs:
         python-version: ${{ env.min_python_version }}
 
     - name: Install Tox
-      uses: beeware/.github/.github/actions/install-requirement@main
-      with:
-        requirements: tox
-        extra: dev
-        project-root: core
+      run: python -m pip install --group tox-uv
 
     - name: Retrieve Coverage Data
       uses: actions/[email protected]
@@ -205,11 +193,7 @@ jobs:
         python-version: ${{ env.min_python_version }}
 
     - name: Install Tox
-      uses: beeware/.github/.github/actions/install-requirement@main
-      with:
-        requirements: tox
-        extra: dev
-        project-root: core
+      run: python -m pip install --group tox-uv
 
     - name: Get Package
       uses: actions/[email protected]
@@ -220,7 +204,7 @@ jobs:
 
     - name: Test
       run: |
-        export TRAVERTINO_INSTALL_COMMAND="python -m pip install ../$(ls dist/travertino-*.whl)"
+        export TRAVERTINO_INSTALL_COMMAND="uv pip install ../$(ls dist/travertino-*.whl)"
         tox -e trav-compat
 
   testbed:

.github/workflows/pre-commit-update.yml

@@ -11,4 +11,4 @@ jobs:
     uses: beeware/.github/.github/workflows/pre-commit-update.yml@main
     secrets: inherit
     with:
-      pre-commit-source: './core[dev]'
+      pre-commit-source:  "--group pre-commit"

.gitignore

@@ -1,3 +1,7 @@
+# MkDocs
+_build
+comment.md
+
 *.pyc
 *~
 .*.sw[op]
@@ -10,7 +14,6 @@ coverage.xml
 dist
 build
 logs
-_build
 distribute-*
 docs/env
 local

.pre-commit-config.yaml

@@ -6,7 +6,6 @@ repos:
       - id: check-toml
       - id: check-yaml
       - id: check-case-conflict
-      - id: check-docstring-first
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit

.pyspelling.yml

@@ -0,0 +1,57 @@
+matrix:
+- name: markdown
+  dictionary:
+    wordlists:
+    - docs/spelling_wordlist
+    output: _build/dictionary/python.dic
+  sources:
+  - 'docs/**/*.md'
+  pipeline:
+  - pyspelling.filters.markdown:
+      markdown_extensions:
+      - markdown.extensions.toc
+      - markdown.extensions.admonition
+      - markdown.extensions.attr_list
+      - pymdownx.superfences
+      - pymdownx.blocks.admonition
+      - pymdownx.blocks.caption
+      - pymdownx.blocks.tab
+      - pymdownx.snippets
+  - pyspelling.filters.html:
+      comments: true
+      attributes:
+        - title
+        - alt
+      ignores:
+        - 'code'
+        - 'pre'
+        - 'figure'  # Can be removed once all <figure>s are replaced with Markdown
+        - 'nospell'  # Allows for ignoring a word or words inline.
+  - pyspelling.filters.context:
+      context_visible_first: true
+      escapes: '\\[\\`~]'
+      delimiters:
+        # Ignores the Jinja directives and their contents
+        - open: '{%'
+          content: '[\d\D]*'
+          close: '%}'
+        # Ignores the Jinja directives and their contents
+        - open: '{{'
+          content: '[\d\D]*'
+          close: '}}'
+        # Ignore the mkdocstrings syntax and its content
+        - open: '\['
+          content: '[\d\D]*\]\[[\d\D]*'
+          close: '\]'
+        # Ignore the mkdocstrings syntax and its content
+        - open: ':::'
+          content: '[\d\D]*'
+          close: '\n'
+        # Ignore the single line Snippets syntax
+        - open: '-8<\-'
+          content: '[\d\D]*'
+          close: '\n'
+        # Ignore the multiline Snippets syntax
+        - open: '-8<\-\n'
+          content: '[\d\D]*'
+          close: '-8<-\n'

.readthedocs.yaml

@@ -2,41 +2,23 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
+# Required
 version: 2
 
+# Set the version of Python and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    # Docs are always built on Python 3.12. See also the tox config and contribution docs.
+    # Docs are always built on Python 3.12. See also the tox config.
     python: "3.12"
   jobs:
     post_checkout:
-      # RTD defaults to a depth of 50 but Toga versioning may require
-      # much more git history to accurately determine the SCM version
       - git fetch --unshallow
+    pre_install:
+      - python -m pip install --upgrade pip
+      - python -m pip install --group 'tox-uv'
     pre_build:
-      - tox -e docs-lint
-
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  builder: html
-  configuration: docs/conf.py
-  fail_on_warning: true
-
-# Install extras for build. Order is significant; each entry is a separate call to
-# `pip`, and we need Travertino to exist before core is installed. core[dev] is needed
-# to run `tox -e docs-lint` as a pre-build step.
-python:
-  install:
-  # Docs requirements are *mostly* handled by the `docs` extra; but we can't include
-  # the theme that way, so the theme is installed using a requirements.txt file,
-  # independent of the docs extra. Ideally, we'd use dependency groups for docs
-  # dependencies, but RTD doesn't support them yet.
-  - requirements: requirements-docs.txt
-  - method: pip
-    path: travertino
-  - method: pip
-    path: core
-    extra_requirements:
-      - dev
-      - docs
+      - python -m tox -e docs-lint
+    build:
+      html:
+        - python -m tox -e docs-$READTHEDOCS_LANGUAGE -- --output=$READTHEDOCS_OUTPUT/html/

.rumdl.toml

@@ -0,0 +1,30 @@
+[global]
+flavor = "mkdocs"
+include = ["**/*.md"]
+exclude = ["CONTRIBUTING.md", "README.md", "changes/template.md", "winforms", "comment.md"]
+respect-gitignore = true
+force-exclude = true
+
+# Disable rules:
+# MD013: Line length - flagging on mkdocstrings content
+# MD014: Forces commands in codeblocks to show output
+# MD042: Empty link - buggy, still flagging on valid MkDocs formatting
+# MD052: Reference link not found - buggy, flagging on valis MkDocs links
+disable = ["MD013", "MD014", "MD042", "MD052"]
+
+[per-file-ignores]
+"changes/**/*.md" = ["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
+
+[MD046]
+style = "fenced"

changes/3138.misc.1.md

@@ -0,0 +1 @@
+Examples no longer use `style=Pack` syntax, and now import constants from `toga.constants`.

changes/3580.bugfix.md

@@ -0,0 +1 @@
+The minimum width hint of the iOS `DateInput` and `TimeInput` widgets will now fit to the actual displayed size of the picker.

changes/3609.feature.md

@@ -0,0 +1 @@
+`ListSource.find` now has a `default` parameter which is returned when no match is found.

changes/3611.bugfix.md

@@ -0,0 +1 @@
+The `rgb` and `hsl` classes, in addition to their copy-pasteable-into-Python `__repr__`, gain a `__str__` that uses modern CSS syntax. For `rgb` this is simply a nice update, but for `hsl` it corrects color rendering issues when using the web backend.

changes/3611.removal.1.md

@@ -0,0 +1 @@
+Previously, Travertino provided an `rgba` and an `hsla` class, as well as `rgb` and `hsl` subclasses that enforce opaque alpha. In order to better match CSS, there is now no difference between these names; the shorter `rgb` and `hsl` are the preferred forms, but `rgba` and `hsla` are direct aliases for them. This can have backwards-incompatible implications; for instance, `rgba(255, 255, 255, .5).rgb` would previously have returned a fully opaque `rgb` instance, while now it will preserve its alpha channel information.

changes/3611.removal.2.md

@@ -0,0 +1 @@
+In order to better match CSS, the `rgb` and `hsl` constructors now silently clip (or in the case of hue, wrap) out-of-range values rather than throwing errors. They also convert them to consistent types: integers for red, blue, green, and hue; and floats for saturation, lightness, and alpha.

changes/3611.removal.3.md

@@ -0,0 +1 @@
+`rgb` and `hsl` color objects are now read-only; their `r`/`g`/`b`/`a` or `h`/`s`/`l`/`a` attributes can't be altered after creation. Because of this, format conversions (`rgb(...).hsl` or `hsl(...).rgb`) can now cache their results, only performing calculations once. "Converting" a color object to its own type (`rgb(...).rgb` or `hsl(...).hsl`) now returns the original object, rather than a new instance with the same values.

changes/3611.removal.4.md

@@ -0,0 +1 @@
+Travertino's color-parsing `color()` function interprets hex strings, e.g. `#123`, `#112233`, as well as predefined named colors. Previously, while this was never documented, it also parsed CSS-like declarations like `"rgb(...)"`; this feature has been removed.

changes/3631.feature.md

@@ -0,0 +1 @@
+Pack now has a `font` shorthand property for specifying all font properties at once.

changes/3655.misc.rst → changes/3655.misc.md

@@ -1 +1 @@
-Travertino's optional dev dependencies have been removed, since its testing is handled by the overall tox configuration and uses core[dev].
+Travertino's optional dev dependencies have been removed, since its testing is handled by the overall tox configuration and uses core\[dev\].

changes/3663.misc.md

@@ -0,0 +1 @@
+Updated coverage\[toml\] from 7.9.2 to 7.10.1 in /core.

changes/3669.bugfix.md

@@ -0,0 +1 @@
+App path attributes were unintentionally made writeable in 0.5.2, e.g. one could reassign `app.paths.config = <something>`. This has been fixed.

changes/3672.bugfix.md

@@ -0,0 +1 @@
+An issue with the text of OptionContainer tab labels being returned as a `rubicon.objc.collections.ObjCStrInstance` on macOS instead of a Python `str` has been fixed.

changes/3688.misc.md

@@ -0,0 +1 @@
+Updated coverage\[toml\] from 7.10.1 to 7.10.2 in /core.

changes/3712.misc.md

@@ -0,0 +1 @@
+Updated coverage\[toml\] from 7.10.2 to 7.10.4 in /core.

changes/3719.doc.md

@@ -0,0 +1 @@
+Toga's documentation was migrated to Markdown format.

changes/3720.misc.md

@@ -0,0 +1 @@
+Updated coverage\[toml\] from 7.10.4 to 7.10.5 in /core.

changes/3738.misc.md

@@ -0,0 +1 @@
+Updated coverage\[toml\] from 7.10.5 to 7.10.6 in /core.

changes/3770.misc.md

@@ -0,0 +1 @@
+Updated coverage\[toml\] from 7.10.6 to 7.10.7 in /core.

changes/template.rst → changes/template.md

@@ -1,13 +1,12 @@
 {% for section, _ in sections.items() %}
-{% set underline = underlines[0] %}{% if section %}{{section}}
-{{ underline * section|length }}{% set underline = underlines[1] %}
+{% if section %}
+{{section}}
 
 {% endif %}
 
 {% if sections[section] %}
 {% for category, val in definitions.items() if category in sections[section]%}
-{{ definitions[category]['name'] }}
-{{ underline * definitions[category]['name']|length }}
+### {{ definitions[category]['name'] }}
 
 {% if definitions[category]['showcontent'] %}
 {% for text, values in sections[section][category].items() %}

core/pyproject.toml

@@ -57,39 +57,18 @@ classifiers = [
     "Topic :: Software Development :: Widget Sets",
 ]
 
-[project.optional-dependencies]
+[dependency-groups]
 # Extras used by developers *of* Toga are pinned to specific versions to
 # ensure environment consistency.
 dev = [
     "coverage[toml] == 7.10.7",
     "coverage-conditional-plugin == 0.9.0",
     "Pillow == 11.3.0",
-    "pre-commit == 4.3.0",
     "pytest == 8.4.2",
     "pytest-asyncio == 1.2.0",
     "pytest-freezer == 0.4.9",
     "pytest-xdist == 3.8.0",
-    "setuptools-scm == 9.2.0",
-    "tox == 4.30.3",
-]
-# Docs are always built on a specific Python version; see RTD and tox config files,
-# and the docs contribution guide.
-docs = [
-    # Docs requirements are *mostly* handled by the `docs` extra; but we can't include
-    # the theme that way, so the theme is installed using a requirements.txt file,
-    # independent of the docs extra. Ideally, we'd use dependency groups for docs
-    # dependencies, but RTD doesn't support them yet.
-    # "beeware_theme @ git+https://github.com/beeware/beeware-theme",
-    "furo == 2025.9.25",
-    "Pillow == 11.3.0",
-    "pyenchant == 3.3.0",
-    "sphinx == 8.2.3",
-    "sphinx_tabs == 3.4.5",
-    "sphinx-autobuild == 2024.10.3",
-    "sphinx-csv-filter == 0.4.2",
-    "sphinx-copybutton == 0.5.2",
-    "sphinx-toolbox == 4.0.0",
-    "sphinxcontrib-spelling == 8.0.1",
+    "setuptools-scm==9.2.0",
 ]
 
 [project.urls]