Move documentation to Markdown and MkDocs

.github/workflows/ci.yml

@@ -47,25 +47,40 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        platform: ["macOS-latest", "windows-latest", "ubuntu-latest"]
+        include:
+          - name: macOS
+            platform: macOS-latest
+
+          - name: windows
+            platform: windows-latest
+
+          - name: ubuntu-24.04
+            platform: ubuntu-24.04
+            system-dependencies: |
+              sudo apt-get update
+              sudo apt install gir1.2-gtk-3.0 gir1.2-webkit2-4.1 \
+                libcairo2-dev libcanberra-gtk3-module libgirepository-2.0-0 \
+                libgirepository-2.0-dev
 
     steps:
       - name: Checkout
         uses: actions/checkout@v6.0.2
         with:
           fetch-depth: 0
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6.2.0
-        with:
-          python-version: 3.14
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Install system dependencies
+        if: matrix.system-dependencies
+        run: ${{ matrix.system-dependencies }}
 
-      - name: Install dependencies
+      - name: Build package
         run: |
-          uvx briefcase package
+          uvx briefcase package --adhoc-sign
 
       - name: Upload artefacts
         uses: actions/upload-artifact@v7.0.1
         with:
-          name: installer-${{ matrix.platform }}
+          name: installer-${{ matrix.name }}
           path: dist

.pre-commit-config.yaml

@@ -19,6 +19,10 @@ repos:
       - id: ruff-format
       - id: ruff-check
         args: [--fix]
+  - repo: https://github.com/rvben/rumdl-pre-commit
+    rev: v0.1.87
+    hooks:
+      - id: rumdl
   # - repo: https://github.com/codespell-project/codespell
   #   rev: v2.4.2
   #   hooks:

.pyspelling.yml

@@ -0,0 +1,69 @@
+matrix:
+- name: markdown
+  aspell:
+    lang: en
+    d: en_US
+    mode:
+      - markdown
+      - url
+      - email
+  dictionary:
+    wordlists:
+    - docs/spelling_wordlist
+    output: _build/dictionary/python.dic
+  sources:
+  - 'docs/**/*.md'
+  - README.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.details
+  - pyspelling.filters.html:
+      comments: false
+      attributes:
+        - title
+        - alt
+      ignores:
+        - 'code'
+        - 'pre'
+        - 'nospell'
+  - pyspelling.filters.context:
+      context_visible_first: true
+      delimiters:
+        # Ignore the Jinja directives
+        - open: '{% '
+          close: ' %}'
+        # Ignores the autorefs link targets
+        - open: '\]\['
+          close: '\]'
+        # Ignore the single line Snippets syntax
+        - open: '-8<- '
+          close: '$'
+        # Ignore the .md URLs - appears to be fixed by mode: url above, leaving in place for now
+        #- open: 'https?:'
+        #  close: '\.md(:[-\w]+)?'
+        # Ignore urls in frontmatter - This is still necessary with mode: url
+        - open: 'url: '
+          close: '$'
+        # Ignore toc in frontmatter
+        - open: '- toc'
+          close: '$'
+        # Ignore numbers with a suffix, e.g. dates
+        - open: '[0-9]+'
+          close: '[rshndt]*'
+        # Ignore version numbers
+        - open: '[0-9\.]+[a-z]*'
+          close: '[0-9]*'
+        # Ignore URLs in Markdown links - This shouldn't be necessary, but here we are.
+        - open: '\]\('
+          close: '\)'
+        # Ignore attrlist class names
+        - open: '\{ \.'
+          close: '\}'

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# 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-24.04
+  tools:
+    # Docs are always built on Python 3.13. See also the tox config.
+    python: "3.13"
+  jobs:
+    pre_install:
+      - python -m pip install --upgrade pip
+      - python -m pip install --group 'tox-uv'
+    build:
+      html:
+        - python -m tox -e docs-all -- --output=$READTHEDOCS_OUTPUT/html/

README.md

@@ -0,0 +1,92 @@
+# Podium
+
+[![image](https://beeware.org/project/projects/applications/podium/podium.png){width="72px"}](https://beeware.org/project/projects/applications/podium)
+
+[![Discord server](https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic)](https://beeware.org/bee/chat/)
+
+A markup-based slide presentation tool.
+
+## Why?
+
+## Quickstart
+
+Official releases of Podium can be downloaded from the [GitHub releases page](https://github.com/beeware/podium/releases).
+
+Download the binary for your platform of choice, and run it. This should open a file dialog, prompting you to open a `.podium` slide deck. An example Podium slide deck is also available in the releases folder. Unzip the deck, and open it in Podium.
+
+Controls from here are keyboard based:
+
+- CMD-Shift-P - Enter presentation mode; or, if in presentation mode, Pause timer
+- CMD-P - Open presentation in Print view
+- Esc - Exit presentation mode
+- CMD-Tab - Switch displays
+- Right/Left arrows - Next/previous slide
+- Down/Up arrows - Next/previous slide
+- Enter - Next slide
+- Home/End - first/last slide
+- CMD-A - Switch aspect ratio between 16:9 and 4:3
+- CMD-R - Reload slide deck
+- CMD-T - Reset timer
+
+If you're on Linux, "CMD" is the Control key.
+
+## Developing Podium
+
+Podium uses the [BeeWare](https://beeware.org) suite of tools and libraries -most notably, the [Toga](https://github.com/beeware/toga) widget toolkit, and the [Briefcase](https://github.com/beeware/briefcase) packaging tool.
+
+To develop Podium, create a virtual environment, and install the BeeWare tools.
+
+Then, you can create a virtual environment and install the BeeWare tools:
+
+    $ mkdir beeware
+    $ cd beeware
+    $ python3 -m venv venv
+    $ source venv/bin/activate
+    (venv) $ pip install briefcase
+
+Now that you have the code, you can clone the Podium repository and run it in developer mode:
+
+    (venv) $ git clone https://github.com/beeware/podium.git
+    (venv) $ cd podium
+    (venv) $ briefcase dev
+
+This should open the same file dialog as before.
+
+### Packaging with Briefcase
+
+Use [Briefcase](https://github.com/beeware/briefcase) to package this repository as a standalone application:
+
+    $ briefcase package
+
+Depending on your platform, this will produce a `macOS` folder containing a Podium DMG file, or a `linux` folder containing a system package appropriate to your distribution (a <span class="title-ref">.deb</span>, <span class="title-ref">.rpm</span> or <span class="title-ref">.pkg.zip</span> file)
+
+## Overriding Default themes
+
+Define a <span class="title-ref">style.css</span> file to override the default theme. You can use the **Debugging** section to help you create a theme that suites your style.
+
+## Debugging
+
+If you need to debug the CSS for a slide, you may want to use the "inspect element" feature of the webview. You may need to manually enable the feature at an operating system level:
+
+- **macOS**: at a terminal prompt, run:
+
+    > defaults write org.beeware.podium WebKitDeveloperExtras -bool true
+
+## Documentation
+
+Documentation for Podium can be found on [Read The Docs](https://podium-app.readthedocs.io/en/latest/).
+
+## Community
+
+Podium is part of the [BeeWare suite](https://beeware.org). You can talk to the community through:
+
+- [@beeware@fosstodon.org on Mastodon](https://fosstodon.org/@beeware)
+- [Discord](https://beeware.org/bee/chat/)
+
+We foster a welcoming and respectful community as described in our [BeeWare Community Code of Conduct](https://beeware.org/community/behavior/).
+
+## Contributing
+
+If you experience problems with Podium, [log them on GitHub](https://github.com/beeware/podium/issues).
+
+If you want to contribute, please [fork the project](https://github.com/beeware/podium) and [submit a pull request](https://github.com/beeware/podium/pulls).