diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 97e1072bb..4a09c81e2 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -12,20 +12,19 @@ updates: directory: "/" patterns: ["*"] multi-ecosystem-group: "dependencies" - - - package-ecosystem: "pre-commit" - directory: "/" - patterns: ["*"] - multi-ecosystem-group: "dependencies" + cooldown: + default-days: 7 - package-ecosystem: "pip" directory: "/" patterns: ["*"] multi-ecosystem-group: "dependencies" + cooldown: + default-days: 7 - package-ecosystem: "pre-commit" directory: "/" - schedule: - # Check for updates on the first Sunday of every month, 8PM UTC - interval: "cron" - cronjob: "0 20 * * sun#1" + patterns: ["*"] + multi-ecosystem-group: "dependencies" + cooldown: + default-days: 7 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 17c29cee3..a93c1d09a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,8 @@ name: CI + +permissions: + contents: read + on: pull_request: push: @@ -24,9 +28,12 @@ jobs: towncrier: name: Check towncrier + permissions: + contents: read + pull-requests: write uses: beeware/.github/.github/workflows/towncrier-run.yml@main with: - tox-source: "--group tox-uv" + tox-source: "--group tox" package: name: Package Colosseum @@ -46,35 +53,35 @@ jobs: strategy: fail-fast: false matrix: - python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14", "3.15" ] + python-version: [ "3.11", "3.12", "3.13", "3.14", "3.15" ] include: # Builds must pass by default - experimental: false # Development Python can fail without failing the entire job - - python-version: "3.14" + - python-version: "3.15" experimental: true steps: - name: Checkout - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 + persist-credentials: false - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v7.0.0 + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: ${{ matrix.python-version }} allow-prereleases: true - name: Get Packages - uses: actions/download-artifact@v8.0.1 + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: name: ${{ needs.package.outputs.artifact-name }} path: dist - name: Install Tox - run: python -m pip install --group tox-uv - + run: python -m pip install --group tox - name: Test run: tox -e py --installpkg dist/colosseum-*.whl diff --git a/.github/workflows/dependabot-changenote.yml b/.github/workflows/dependabot-changenote.yml index 17848bc9e..8aca64bd4 100644 --- a/.github/workflows/dependabot-changenote.yml +++ b/.github/workflows/dependabot-changenote.yml @@ -8,5 +8,8 @@ on: jobs: changenote: name: Dependabot Change Note + permissions: + contents: read uses: beeware/.github/.github/workflows/dependabot-changenote.yml@main - secrets: inherit + secrets: + BRUTUS_PAT_TOKEN: ${{ secrets.BRUTUS_PAT_TOKEN }} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 1733a2bfa..3b03a8c39 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -11,7 +11,7 @@ jobs: # This permission is required for trusted publishing. id-token: write steps: - - uses: dsaltares/fetch-gh-release-asset@1.1.2 + - uses: dsaltares/fetch-gh-release-asset@aa2ab1243d6e0d5b405b973c89fa4d06a2d0fff7 # 1.1.2 with: version: tags/${{ github.event.release.tag_name }} file: ${{ github.event.repository.name }}.* @@ -19,4 +19,4 @@ jobs: target: dist/ - name: Publish release to production PyPI - uses: pypa/gh-action-pypi-publish@release/v1 + uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1916a31d2..eac60a48b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,5 +1,8 @@ name: Create Release +permissions: + contents: read + on: push: tags: @@ -8,6 +11,10 @@ on: jobs: ci: name: CI + permissions: + contents: read + id-token: write + attestations: write uses: ./.github/workflows/ci.yml with: attest-package: "true" @@ -26,12 +33,12 @@ jobs: echo "VERSION=${GITHUB_REF_NAME#v}" | tee -a $GITHUB_ENV - name: Set up Python - uses: actions/setup-python@v7.0.0 + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.x" - name: Get packages - uses: actions/download-artifact@v8.0.1 + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: name: ${{ needs.ci.outputs.artifact-name }} path: dist @@ -47,14 +54,17 @@ jobs: test $(python -c "from colosseum import __version__; print(__version__)") = $VERSION - name: Create release - uses: ncipollo/release-action@v1.21.0 - with: - name: ${{ env.VERSION }} - draft: true - artifacts: dist/* - artifactErrorsFailBuild: true + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: | + gh release create "${GITHUB_REF_NAME}" \ + --title "${VERSION}" \ + --draft \ + --verify-tag \ + dist/* - name: Publish release to Test PyPI - uses: pypa/gh-action-pypi-publish@release/v1 + uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2 with: - repository_url: https://test.pypi.org/legacy/ + repository-url: https://test.pypi.org/legacy/ diff --git a/.github/zizmor.yml b/.github/zizmor.yml new file mode 100644 index 000000000..b834affdd --- /dev/null +++ b/.github/zizmor.yml @@ -0,0 +1,9 @@ +rules: + unpinned-uses: + config: + # Allow BeeWare-provided actions to be unpinned. If an attacker is in a + # position to exploit those action, they're probably able to exploit + # repositories directly; and it's significantly easier for our internal + # actions to automatically be the most recent versions. + policies: + beeware/*: ref-pin diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0dfb22d77..06fa86e50 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,6 +4,7 @@ repos: hooks: - id: check-toml - id: check-yaml + args: ['--unsafe'] - id: check-case-conflict - id: check-docstring-first - id: end-of-file-fixer @@ -14,3 +15,11 @@ repos: - id: ruff-format - id: ruff-check args: [ --fix ] + - repo: https://github.com/rvben/rumdl-pre-commit + rev: v0.2.20 + hooks: + - id: rumdl + - repo: https://github.com/zizmorcore/zizmor-pre-commit + rev: v1.27.0 + hooks: + - id: zizmor diff --git a/.pyspelling.yml b/.pyspelling.yml new file mode 100644 index 000000000..b5af3acbe --- /dev/null +++ b/.pyspelling.yml @@ -0,0 +1,62 @@ +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/en/**/*.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 + - pyspelling.filters.html: + comments: true + attributes: + - title + - alt + ignores: + - 'code' + - 'pre' + - '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 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]*' + 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' diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..b5d7d013f --- /dev/null +++ b/.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 + +version: 2 + +build: + os: ubuntu-24.04 + tools: + # Docs are always built on Python 3.13. See also the tox config. + python: "3.13" + jobs: + post_checkout: + - git fetch --unshallow + pre_install: + - python -m pip install --upgrade pip + - python -m pip install --group tox + build: + html: + - python -m tox -e docs-all -- --output=$READTHEDOCS_OUTPUT/html/ diff --git a/CHANGELOG.rst b/CHANGELOG.rst deleted file mode 100644 index d82d3882b..000000000 --- a/CHANGELOG.rst +++ /dev/null @@ -1,5 +0,0 @@ -Changelog -========= - -A complete history of the changes to Colosseum can be found in `Colosseum's -documentation <./docs/background/releases.rst>`__. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7784e4e2f..ec4f1c03a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing -PyBee <3's contributions! +BeeWare <3's contributions! -Please be aware, PyBee operates under a Code of Conduct. +Please be aware, BeeWare operates under a Code of Conduct. -See [CONTRIBUTING to PyBee](http://pybee.org/contributing) for details. +See [CONTRIBUTING to BeeWare](https://beeware.org/contributing) for details. diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 79cd1489c..000000000 --- a/MANIFEST.in +++ /dev/null @@ -1,25 +0,0 @@ -include CHANGELOG.rst -include CONTRIBUTING.md -include README.rst -include AUTHORS -include LICENSE -include docs/spelling_wordlist -include pyproject.toml -include tox.ini -recursive-include changes *.rst -recursive-include src *.py -recursive-include docs *.bat -recursive-include docs *.png -recursive-include docs *.py -recursive-include docs *.rst -recursive-include docs *.txt -recursive-include docs Makefile -recursive-exclude docs/_build * -recursive-include tests *.py -recursive-include tests *.json -recursive-include tests not_implemented -recursive-include utils *.js -recursive-include utils *.py -recursive-include utils *.rst -recursive-include utils *.sh -recursive-include utils *.tpy diff --git a/README.md b/README.md index 47203e3bf..557450f83 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,37 @@ -[](https://beeware.org/colosseum) - # Colosseum -[![image](https://img.shields.io/pypi/pyversions/colosseum.svg)](https://pypi.python.org/pypi/colosseum) -[![image](https://img.shields.io/pypi/v/colosseum.svg)](https://pypi.python.org/pypi/colosseum) -[![image](https://img.shields.io/pypi/status/colosseum.svg)](https://pypi.python.org/pypi/colosseum) -[![image](https://img.shields.io/pypi/l/colosseum.svg)](https://github.com/beeware/colosseum/blob/main/LICENSE) -[![Build Status](https://github.com/beeware/colosseum/workflows/CI/badge.svg?branch=main)](https://github.com/beeware/colosseum/actions) -[![Discord server](https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic)](https://beeware.org/bee/chat/) +[![Toga](https://beeware.org/static/images/defaultlogo.png)](https://colosseum.beeware.org) + +[![image](https://img.shields.io/pypi/pyversions/colosseum.svg)](https://pypi.python.org/pypi/colosseum) [![image](https://img.shields.io/pypi/v/colosseum.svg)](https://pypi.python.org/pypi/colosseum) [![image](https://img.shields.io/pypi/status/colosseum.svg)](https://pypi.python.org/pypi/colosseum) [![image](https://img.shields.io/pypi/l/colosseum.svg)](https://github.com/beeware/colosseum/blob/main/LICENSE) [![Build Status](https://github.com/beeware/colosseum/workflows/CI/badge.svg?branch=main)](https://github.com/beeware/colosseum/actions) [![Discord server](https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic)](https://beeware.org/bee/chat/) -An independent implementation of the CSS layout algorithm. This -implementation is completely standalone - it isn't dependent on a -browser, and can be run over any box-like set of objects that need to be -laid out on a page (either physical or virtual) +An independent implementation of the CSS layout algorithm. This implementation is completely standalone - it isn't dependent on a browser, and can be run over any box-like set of objects that need to be laid out on a page (either physical or virtual) ## Tutorial -Want to jump in and get started? We have a [hands-on tutorial for -beginners](https://colosseum.readthedocs.io/en/latest/tutorial/tutorial-1.html) +Want to jump in and get started? We have a [hands-on tutorial for beginners](https://colosseum.readthedocs.io/en/latest/tutorial/tutorial-1.html) ## How-to guides -Looking for guidance on how to solve a specific problems? We have -[how-to guides and -recipes](https://colosseum.readthedocs.io/en/latest/how-to/index.html) -for common problems and tasks, including how to contribute. +Looking for guidance on how to solve a specific problems? We have [how-to guides and recipes](https://colosseum.readthedocs.io/en/latest/how-to/index.html) for common problems and tasks, including how to contribute. ## Reference -Just want the raw technical details? Here's our [Technical -reference](https://colosseum.readthedocs.io/en/latest/reference/index.html). +Just want the raw technical details? Here's our [Technical reference](https://colosseum.readthedocs.io/en/latest/reference/index.html). ## Background -Looking for explanations and discussion of key topics and concepts? Our -[background](https://colosseum.readthedocs.io/en/latest/background/index.html) -guides may help. +Looking for explanations and discussion of key topics and concepts? Our [background](https://colosseum.readthedocs.io/en/latest/background/index.html) guides may help. ## Community -Colosseum is part of the [BeeWare suite](https://beeware.org). You can -talk to the community through: +Colosseum 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/) -- The Colosseum [Github Discussions - forum](https://github.com/beeware/colosseum/discussions) +- The Colosseum [Github Discussions forum](https://github.com/beeware/colosseum/discussions) -We foster a welcoming and respectful community as described in our -[BeeWare Community Code of -Conduct](https://beeware.org/community/behavior/). +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 Colosseum, [log them on -GitHub](https://github.com/beeware/colosseum/issues). If you want to -contribute code, please [fork the -code](https://github.com/beeware/colosseum) and [submit a pull -request](https://github.com/beeware/colosseum/pulls). +If you experience problems with Colosseum, [log them on GitHub](https://github.com/beeware/colosseum/issues). If you want to contribute code, please [fork the code](https://github.com/beeware/colosseum) and [submit a pull request](https://github.com/beeware/colosseum/pulls). diff --git a/changes/101.misc.rst b/changes/101.misc.md similarity index 100% rename from changes/101.misc.rst rename to changes/101.misc.md diff --git a/changes/102.misc.rst b/changes/102.misc.md similarity index 100% rename from changes/102.misc.rst rename to changes/102.misc.md diff --git a/changes/103.misc.rst b/changes/103.misc.md similarity index 100% rename from changes/103.misc.rst rename to changes/103.misc.md diff --git a/changes/104.misc.rst b/changes/104.misc.md similarity index 100% rename from changes/104.misc.rst rename to changes/104.misc.md diff --git a/changes/105.misc.rst b/changes/105.misc.md similarity index 100% rename from changes/105.misc.rst rename to changes/105.misc.md diff --git a/changes/106.misc.rst b/changes/106.misc.md similarity index 100% rename from changes/106.misc.rst rename to changes/106.misc.md diff --git a/changes/107.misc.rst b/changes/107.misc.md similarity index 100% rename from changes/107.misc.rst rename to changes/107.misc.md diff --git a/changes/108.misc.rst b/changes/108.misc.md similarity index 100% rename from changes/108.misc.rst rename to changes/108.misc.md diff --git a/changes/109.misc.rst b/changes/109.misc.md similarity index 100% rename from changes/109.misc.rst rename to changes/109.misc.md diff --git a/changes/110.misc.rst b/changes/110.misc.md similarity index 100% rename from changes/110.misc.rst rename to changes/110.misc.md diff --git a/changes/111.misc.rst b/changes/111.misc.md similarity index 100% rename from changes/111.misc.rst rename to changes/111.misc.md diff --git a/changes/112.misc.rst b/changes/112.misc.md similarity index 100% rename from changes/112.misc.rst rename to changes/112.misc.md diff --git a/changes/113.misc.rst b/changes/113.misc.md similarity index 100% rename from changes/113.misc.rst rename to changes/113.misc.md diff --git a/changes/114.misc.rst b/changes/114.misc.md similarity index 100% rename from changes/114.misc.rst rename to changes/114.misc.md diff --git a/changes/115.misc.rst b/changes/115.misc.md similarity index 100% rename from changes/115.misc.rst rename to changes/115.misc.md diff --git a/changes/116.misc.rst b/changes/116.misc.md similarity index 100% rename from changes/116.misc.rst rename to changes/116.misc.md diff --git a/changes/117.misc.rst b/changes/117.misc.md similarity index 100% rename from changes/117.misc.rst rename to changes/117.misc.md diff --git a/changes/118.misc.rst b/changes/118.misc.md similarity index 100% rename from changes/118.misc.rst rename to changes/118.misc.md diff --git a/changes/119.misc.rst b/changes/119.misc.md similarity index 100% rename from changes/119.misc.rst rename to changes/119.misc.md diff --git a/changes/120.misc.rst b/changes/120.misc.md similarity index 100% rename from changes/120.misc.rst rename to changes/120.misc.md diff --git a/changes/121.misc.rst b/changes/121.misc.md similarity index 100% rename from changes/121.misc.rst rename to changes/121.misc.md diff --git a/changes/122.misc.rst b/changes/122.misc.md similarity index 100% rename from changes/122.misc.rst rename to changes/122.misc.md diff --git a/changes/123.misc.rst b/changes/123.misc.md similarity index 100% rename from changes/123.misc.rst rename to changes/123.misc.md diff --git a/changes/124.misc.rst b/changes/124.misc.md similarity index 100% rename from changes/124.misc.rst rename to changes/124.misc.md diff --git a/changes/125.misc.rst b/changes/125.misc.md similarity index 100% rename from changes/125.misc.rst rename to changes/125.misc.md diff --git a/changes/126.misc.rst b/changes/126.misc.md similarity index 100% rename from changes/126.misc.rst rename to changes/126.misc.md diff --git a/changes/127.misc.rst b/changes/127.misc.md similarity index 100% rename from changes/127.misc.rst rename to changes/127.misc.md diff --git a/changes/128.misc.rst b/changes/128.misc.md similarity index 100% rename from changes/128.misc.rst rename to changes/128.misc.md diff --git a/changes/129.misc.rst b/changes/129.misc.md similarity index 100% rename from changes/129.misc.rst rename to changes/129.misc.md diff --git a/changes/130.misc.rst b/changes/130.misc.md similarity index 100% rename from changes/130.misc.rst rename to changes/130.misc.md diff --git a/changes/131.misc.rst b/changes/131.misc.md similarity index 100% rename from changes/131.misc.rst rename to changes/131.misc.md diff --git a/changes/132.misc.rst b/changes/132.misc.md similarity index 100% rename from changes/132.misc.rst rename to changes/132.misc.md diff --git a/changes/133.misc.rst b/changes/133.misc.md similarity index 100% rename from changes/133.misc.rst rename to changes/133.misc.md diff --git a/changes/134.misc.rst b/changes/134.misc.md similarity index 100% rename from changes/134.misc.rst rename to changes/134.misc.md diff --git a/changes/135.misc.rst b/changes/135.misc.md similarity index 100% rename from changes/135.misc.rst rename to changes/135.misc.md diff --git a/changes/136.misc.rst b/changes/136.misc.md similarity index 100% rename from changes/136.misc.rst rename to changes/136.misc.md diff --git a/changes/137.misc.rst b/changes/137.misc.md similarity index 100% rename from changes/137.misc.rst rename to changes/137.misc.md diff --git a/changes/138.misc.rst b/changes/138.misc.md similarity index 100% rename from changes/138.misc.rst rename to changes/138.misc.md diff --git a/changes/139.misc.rst b/changes/139.misc.md similarity index 100% rename from changes/139.misc.rst rename to changes/139.misc.md diff --git a/changes/140.misc.rst b/changes/140.misc.md similarity index 100% rename from changes/140.misc.rst rename to changes/140.misc.md diff --git a/changes/142.misc.rst b/changes/142.misc.md similarity index 100% rename from changes/142.misc.rst rename to changes/142.misc.md diff --git a/changes/144.misc.rst b/changes/144.misc.md similarity index 100% rename from changes/144.misc.rst rename to changes/144.misc.md diff --git a/changes/145.misc.rst b/changes/145.misc.md similarity index 100% rename from changes/145.misc.rst rename to changes/145.misc.md diff --git a/changes/146.misc.rst b/changes/146.misc.md similarity index 100% rename from changes/146.misc.rst rename to changes/146.misc.md diff --git a/changes/147.misc.rst b/changes/147.misc.md similarity index 100% rename from changes/147.misc.rst rename to changes/147.misc.md diff --git a/changes/148.misc.rst b/changes/148.misc.md similarity index 100% rename from changes/148.misc.rst rename to changes/148.misc.md diff --git a/changes/149.misc.rst b/changes/149.misc.md similarity index 100% rename from changes/149.misc.rst rename to changes/149.misc.md diff --git a/changes/150.misc.rst b/changes/150.misc.md similarity index 100% rename from changes/150.misc.rst rename to changes/150.misc.md diff --git a/changes/151.misc.rst b/changes/151.misc.md similarity index 100% rename from changes/151.misc.rst rename to changes/151.misc.md diff --git a/changes/152.misc.rst b/changes/152.misc.md similarity index 100% rename from changes/152.misc.rst rename to changes/152.misc.md diff --git a/changes/153.misc.rst b/changes/153.misc.md similarity index 100% rename from changes/153.misc.rst rename to changes/153.misc.md diff --git a/changes/154.misc.rst b/changes/154.misc.md similarity index 100% rename from changes/154.misc.rst rename to changes/154.misc.md diff --git a/changes/155.misc.rst b/changes/155.misc.md similarity index 100% rename from changes/155.misc.rst rename to changes/155.misc.md diff --git a/changes/156.misc.rst b/changes/156.misc.md similarity index 100% rename from changes/156.misc.rst rename to changes/156.misc.md diff --git a/changes/157.misc.rst b/changes/157.misc.md similarity index 100% rename from changes/157.misc.rst rename to changes/157.misc.md diff --git a/changes/158.misc.rst b/changes/158.misc.md similarity index 100% rename from changes/158.misc.rst rename to changes/158.misc.md diff --git a/changes/159.misc.rst b/changes/159.misc.md similarity index 100% rename from changes/159.misc.rst rename to changes/159.misc.md diff --git a/changes/160.misc.rst b/changes/160.misc.md similarity index 100% rename from changes/160.misc.rst rename to changes/160.misc.md diff --git a/changes/161.misc.rst b/changes/161.misc.md similarity index 100% rename from changes/161.misc.rst rename to changes/161.misc.md diff --git a/changes/162.misc.rst b/changes/162.misc.md similarity index 100% rename from changes/162.misc.rst rename to changes/162.misc.md diff --git a/changes/163.misc.rst b/changes/163.misc.md similarity index 100% rename from changes/163.misc.rst rename to changes/163.misc.md diff --git a/changes/164.misc.rst b/changes/164.misc.md similarity index 100% rename from changes/164.misc.rst rename to changes/164.misc.md diff --git a/changes/165.misc.rst b/changes/165.misc.md similarity index 100% rename from changes/165.misc.rst rename to changes/165.misc.md diff --git a/changes/166.misc.rst b/changes/166.misc.md similarity index 100% rename from changes/166.misc.rst rename to changes/166.misc.md diff --git a/changes/167.misc.rst b/changes/167.misc.md similarity index 100% rename from changes/167.misc.rst rename to changes/167.misc.md diff --git a/changes/168.misc.rst b/changes/168.misc.md similarity index 100% rename from changes/168.misc.rst rename to changes/168.misc.md diff --git a/changes/169.misc.rst b/changes/169.misc.md similarity index 100% rename from changes/169.misc.rst rename to changes/169.misc.md diff --git a/changes/170.misc.rst b/changes/170.misc.md similarity index 100% rename from changes/170.misc.rst rename to changes/170.misc.md diff --git a/changes/171.misc.rst b/changes/171.misc.md similarity index 100% rename from changes/171.misc.rst rename to changes/171.misc.md diff --git a/changes/172.misc.rst b/changes/172.misc.md similarity index 100% rename from changes/172.misc.rst rename to changes/172.misc.md diff --git a/changes/173.misc.rst b/changes/173.misc.md similarity index 100% rename from changes/173.misc.rst rename to changes/173.misc.md diff --git a/changes/174.misc.rst b/changes/174.misc.md similarity index 100% rename from changes/174.misc.rst rename to changes/174.misc.md diff --git a/changes/175.misc.rst b/changes/175.misc.md similarity index 100% rename from changes/175.misc.rst rename to changes/175.misc.md diff --git a/changes/176.misc.rst b/changes/176.misc.md similarity index 100% rename from changes/176.misc.rst rename to changes/176.misc.md diff --git a/changes/178.misc.rst b/changes/178.misc.md similarity index 100% rename from changes/178.misc.rst rename to changes/178.misc.md diff --git a/changes/179.misc.rst b/changes/179.misc.md similarity index 100% rename from changes/179.misc.rst rename to changes/179.misc.md diff --git a/changes/180.misc.rst b/changes/180.misc.md similarity index 100% rename from changes/180.misc.rst rename to changes/180.misc.md diff --git a/changes/181.misc.rst b/changes/181.misc.md similarity index 100% rename from changes/181.misc.rst rename to changes/181.misc.md diff --git a/changes/182.misc.rst b/changes/182.misc.md similarity index 100% rename from changes/182.misc.rst rename to changes/182.misc.md diff --git a/changes/183.misc.rst b/changes/183.misc.md similarity index 100% rename from changes/183.misc.rst rename to changes/183.misc.md diff --git a/changes/184.misc.rst b/changes/184.misc.md similarity index 100% rename from changes/184.misc.rst rename to changes/184.misc.md diff --git a/changes/185.misc.rst b/changes/185.misc.md similarity index 100% rename from changes/185.misc.rst rename to changes/185.misc.md diff --git a/changes/186.doc.md b/changes/186.doc.md new file mode 100644 index 000000000..540a35003 --- /dev/null +++ b/changes/186.doc.md @@ -0,0 +1 @@ +Documentation now follows the BeeWare project format. diff --git a/changes/187.misc.rst b/changes/187.misc.md similarity index 100% rename from changes/187.misc.rst rename to changes/187.misc.md diff --git a/changes/188.misc.rst b/changes/188.misc.md similarity index 100% rename from changes/188.misc.rst rename to changes/188.misc.md diff --git a/changes/189.misc.rst b/changes/189.misc.md similarity index 100% rename from changes/189.misc.rst rename to changes/189.misc.md diff --git a/changes/191.doc.rst b/changes/191.doc.md similarity index 100% rename from changes/191.doc.rst rename to changes/191.doc.md diff --git a/changes/192.misc.rst b/changes/192.misc.md similarity index 100% rename from changes/192.misc.rst rename to changes/192.misc.md diff --git a/changes/193.misc.rst b/changes/193.misc.md similarity index 100% rename from changes/193.misc.rst rename to changes/193.misc.md diff --git a/changes/194.misc.rst b/changes/194.misc.md similarity index 100% rename from changes/194.misc.rst rename to changes/194.misc.md diff --git a/changes/195.misc.rst b/changes/195.misc.md similarity index 100% rename from changes/195.misc.rst rename to changes/195.misc.md diff --git a/changes/196.misc.rst b/changes/196.misc.md similarity index 100% rename from changes/196.misc.rst rename to changes/196.misc.md diff --git a/changes/197.misc.rst b/changes/197.misc.md similarity index 100% rename from changes/197.misc.rst rename to changes/197.misc.md diff --git a/changes/198.misc.rst b/changes/198.misc.md similarity index 100% rename from changes/198.misc.rst rename to changes/198.misc.md diff --git a/changes/199.misc.rst b/changes/199.misc.md similarity index 100% rename from changes/199.misc.rst rename to changes/199.misc.md diff --git a/changes/200.misc.rst b/changes/200.misc.md similarity index 100% rename from changes/200.misc.rst rename to changes/200.misc.md diff --git a/changes/202.misc.rst b/changes/202.misc.md similarity index 100% rename from changes/202.misc.rst rename to changes/202.misc.md diff --git a/changes/204.misc.rst b/changes/204.misc.md similarity index 100% rename from changes/204.misc.rst rename to changes/204.misc.md diff --git a/changes/205.misc.rst b/changes/205.misc.md similarity index 100% rename from changes/205.misc.rst rename to changes/205.misc.md diff --git a/changes/206.misc.rst b/changes/206.misc.md similarity index 100% rename from changes/206.misc.rst rename to changes/206.misc.md diff --git a/changes/210.misc.md b/changes/210.misc.md new file mode 100644 index 000000000..3c083e68c --- /dev/null +++ b/changes/210.misc.md @@ -0,0 +1 @@ +Updated Ruff pre-commit diff --git a/changes/210.misc.rst b/changes/210.misc.rst deleted file mode 100644 index 6ab5e09ac..000000000 --- a/changes/210.misc.rst +++ /dev/null @@ -1 +0,0 @@ -Updated https://github.com/astral-sh/ruff-pre-commit. diff --git a/changes/211.misc.rst b/changes/211.misc.md similarity index 100% rename from changes/211.misc.rst rename to changes/211.misc.md diff --git a/changes/212.misc.rst b/changes/212.misc.md similarity index 100% rename from changes/212.misc.rst rename to changes/212.misc.md diff --git a/changes/213.misc.rst b/changes/213.misc.md similarity index 100% rename from changes/213.misc.rst rename to changes/213.misc.md diff --git a/changes/217.misc.rst b/changes/217.misc.md similarity index 100% rename from changes/217.misc.rst rename to changes/217.misc.md diff --git a/changes/230.misc.rst b/changes/230.misc.rst deleted file mode 100644 index 2c79e425a..000000000 --- a/changes/230.misc.rst +++ /dev/null @@ -1 +0,0 @@ -Obsolete pre-commit-update workflow because dependabot supports pre-commit update natively. diff --git a/changes/75.misc.rst b/changes/75.misc.md similarity index 100% rename from changes/75.misc.rst rename to changes/75.misc.md diff --git a/changes/79.misc.rst b/changes/79.misc.md similarity index 100% rename from changes/79.misc.rst rename to changes/79.misc.md diff --git a/changes/229.misc.rst b/changes/86.misc.md similarity index 100% rename from changes/229.misc.rst rename to changes/86.misc.md diff --git a/changes/88.misc.rst b/changes/88.misc.md similarity index 100% rename from changes/88.misc.rst rename to changes/88.misc.md diff --git a/changes/89.misc.rst b/changes/89.misc.md similarity index 100% rename from changes/89.misc.rst rename to changes/89.misc.md diff --git a/changes/90.misc.rst b/changes/90.misc.md similarity index 100% rename from changes/90.misc.rst rename to changes/90.misc.md diff --git a/changes/91.misc.rst b/changes/91.misc.md similarity index 100% rename from changes/91.misc.rst rename to changes/91.misc.md diff --git a/changes/92.misc.rst b/changes/92.misc.md similarity index 100% rename from changes/92.misc.rst rename to changes/92.misc.md diff --git a/changes/93.misc.rst b/changes/93.misc.md similarity index 100% rename from changes/93.misc.rst rename to changes/93.misc.md diff --git a/changes/94.misc.rst b/changes/94.misc.md similarity index 100% rename from changes/94.misc.rst rename to changes/94.misc.md diff --git a/changes/95.misc.rst b/changes/95.misc.md similarity index 100% rename from changes/95.misc.rst rename to changes/95.misc.md diff --git a/changes/96.misc.rst b/changes/96.misc.md similarity index 100% rename from changes/96.misc.rst rename to changes/96.misc.md diff --git a/changes/97.misc.rst b/changes/97.misc.md similarity index 100% rename from changes/97.misc.rst rename to changes/97.misc.md diff --git a/changes/98.misc.rst b/changes/98.misc.md similarity index 100% rename from changes/98.misc.rst rename to changes/98.misc.md diff --git a/changes/99.misc.rst b/changes/99.misc.md similarity index 100% rename from changes/99.misc.rst rename to changes/99.misc.md diff --git a/changes/template.rst b/changes/template.md similarity index 71% rename from changes/template.rst rename to changes/template.md index 9c7243e9f..04b4603c9 100644 --- a/changes/template.rst +++ b/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() %} diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index a6dad46b6..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,181 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build -SOURCEDIR = . - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -VENV = ../env/bin/activate -PORT = 8001 - -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " install to create a virtualenv called 'env' in the docs directory" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " run to start a local autoreloading webserver on port 8001" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/toga.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/toga.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/toga" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/toga" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -spelling: - $(SPHINXBUILD) -b spelling . _build/spelling - @echo - @echo "Check finished. Wrong words can be found in " \ - "build/spelling/output.txt." - -install: - @echo "... setting up virtualenv" - virtualenv env - . $(VENV); pip install -r requirements_docs.txt - @echo "\n" \ - "-------------------------------------------------------------------------------------------------- \n" \ - "* watch, build and serve the documentation: make run \n" \ - "* check spelling: make spelling \n" \ - "\n" \ - "enchant must be installed in order for pyenchant (and therefore spelling checks) to work. See \n" \ - "http://docs.django-cms.org/en/latest/contributing/documentation.html#install-the-spelling-software \n" \ - "-------------------------------------------------------------------------------------------------- \n" \ - -run: - . $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) build/html --host 0.0.0.0 --port $(PORT) diff --git a/docs/background/community.rst b/docs/background/community.rst deleted file mode 100644 index 30c074910..000000000 --- a/docs/background/community.rst +++ /dev/null @@ -1,34 +0,0 @@ -The Colosseum Developer and User community -========================================== - -Colosseum is part of the `BeeWare suite`_. You can talk to the community through: - -* `@beeware@fosstodon.org on Mastodon`_ -* `Discord`_ -* The Colosseum `Github Discussions forum`_ - -Code of Conduct ---------------- - -The BeeWare community has a strict `Code of Conduct`_. All users and -developers are expected to adhere to this code. - -If you have any concerns about this code of conduct, or you wish to report a -violation of this code, please contact the project founder `Russell Keith- -Magee`. - -Contributing ------------- - -If you experience problems with Colosseum, `log them on GitHub`_. If you -want to contribute code, please `fork the code`_ and `submit a pull request`_. - -.. _BeeWare suite: http://pybee.org -.. _@beeware@fosstodon.org on Mastodon: https://fosstodon.org/@beeware -.. _Discord: https://beeware.org/bee/chat/ -.. _Github Discussions forum: https://github.com/beeware/colosseum/discussions -.. _Code of Conduct: http://beeware.org/community/behavior/ -.. _Russell Keith-Magee: mailto:russell@keith-magee.com -.. _log them on Github: https://github.com/pybee/colosseum/issues -.. _fork the code: https://github.com/pybee/colosseum -.. _submit a pull request: https://github.com/pybee/colosseum/pulls diff --git a/docs/background/faq.rst b/docs/background/faq.rst deleted file mode 100644 index ffd02c83d..000000000 --- a/docs/background/faq.rst +++ /dev/null @@ -1,23 +0,0 @@ -========================== -Frequently Asked Questions -========================== - -So... why the name Colosseum? -============================= - -The Colosseum, also known as the Flavian Amphitheater, is an ancient Roman -Amphitheater in the center of Rome. It is an astonding piece of ancient -architecture, noted for it's three layers of arches, framed by Doric, Ionic -and Corinthian half-columns, with an attic decorate with Corinthian pilasters. - -Much like Doric, Ionic and Corithian columns form the fundamental architecture -of the ancient Roman world, CSS is part of the fundamental architecture of -modern display computing. The regular repeating structure of the Colosseum's -arches and columns mirror the regular grid-based layout of many modern web and -print designs. - -The Colosseum was also a massive undertaking for it's time. Undertaking to -reproduce the entire CSS specification, with all it's quirks and -eccentricities, is a similarly massive undertaking. - -But most importantly: the name Colosseum contains, in order, the letters CSS. diff --git a/docs/background/index.rst b/docs/background/index.rst deleted file mode 100644 index 991ab700f..000000000 --- a/docs/background/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _background: - -========== -Background -========== - -Want to know more about the Colosseum project, it's history, community, and -plans for the future? That's what you'll find here! - -.. toctree:: - :maxdepth: 1 - - faq - community - releases - roadmap diff --git a/docs/background/roadmap.rst b/docs/background/roadmap.rst deleted file mode 100644 index ecd4aa734..000000000 --- a/docs/background/roadmap.rst +++ /dev/null @@ -1,2 +0,0 @@ -Colosseum Roadmap -================= diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index c4d9db04d..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,291 +0,0 @@ -# -# Colosseum documentation build configuration file, created by -# sphinx-quickstart on Sat Jul 27 14:58:42 2013. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The full version, including alpha/beta/rc tags. -import os -import re - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -import sys - -sys.path.insert(0, os.path.abspath("../src/core/")) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ["sphinx.ext.autodoc"] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix of source filenames. -source_suffix = ".rst" - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "Colosseum" -copyright = "2013, Russell Keith-Magee" - -with open("../src/colosseum/__init__.py", encoding="utf8") as version_file: - version_match = re.search( - r"^__version__ = ['\"]([^'\"]*)['\"]", version_file.read(), re.MULTILINE - ) - if version_match: - release = version_match.group(1) - else: - raise RuntimeError("Unable to find version string.") - -# The short X.Y version. -version = ".".join(release.split(".")[:2]) - -autoclass_content = "both" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ["_build"] - -# The reST default role (used for this markup: `text`) to use for all documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# on_rtd: whether we are on readthedocs.org -on_rtd = os.environ.get("READTHEDOCS", None) == "True" - -if not on_rtd: # only import and set the theme if we're building docs locally - try: - import sphinx_rtd_theme - except ModuleNotFoundError: - html_theme = "default" - else: - html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = "_static/images/colosseum.png" - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = "colosseumdoc" - -try: - import sphinx_rtd_theme - - html_theme = "sphinx_rtd_theme" -except ImportError: - # The sphinx-rtd-theme package is not installed, so to the default - pass - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - #'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ( - "index", - "colosseum.tex", - "Colosseum Documentation", - "Russell Keith-Magee", - "manual", - ), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ("index", "colosseum", "Colosseum Documentation", ["Russell Keith-Magee"], 1) -] - -# If true, show URL addresses after external links. -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - "index", - "colosseum", - "Colosseum Documentation", - "Russell Keith-Magee", - "Colosseum", - "A bridge between an Objective-C runtime environment and Python.", - "Miscellaneous", - ), -] - -# Documents to append as an appendix to all manuals. -# texinfo_appendices = [] - -# If false, no module index is generated. -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# texinfo_show_urls = 'footnote' - -# -- Options for spelling ------------------------------------------- - -# Spelling check needs an additional module that is not installed by default. -# Add it only if spelling check is requested so docs can be generated without it. -if "spelling" in sys.argv: - extensions.append("sphinxcontrib.spelling") - -# Spelling language. -spelling_lang = "en_US" - -# Location of word list. -spelling_word_list_filename = "spelling_wordlist" - -spelling_ignore_pypi_package_names = True diff --git a/docs/config.yml b/docs/config.yml new file mode 100644 index 000000000..30110ebe0 --- /dev/null +++ b/docs/config.yml @@ -0,0 +1,163 @@ +copyright: © Russell Keith-Magee + +not_in_nav: | + /index.md + +validation: + omitted_files: warn + absolute_links: relative_to_docs + anchors: warn + unrecognized_links: warn + +extra: + project_name: colosseum + package_name: colosseum + formal_name: "Colosseum" + website: false + min_python_version: "3.10" + min_python_version_tag: "310" + recent_python_version: "3.13" + docs_python_version: "3.13" + translated: false + hide_coverage: false + macos_only: false + contribution_guide_root: how-to/contribute + social: + - icon: fontawesome/brands/github + link: https://github.com/beeware + name: BeeWare on GitHub + - icon: fontawesome/brands/mastodon + link: https://fosstodon.org/@beeware + name: BeeWare on Mastodon + - icon: fontawesome/brands/discord + link: https://beeware.org/bee/chat/ + name: BeeWare on Discord + generator: false + +theme: + name: material + language: en + logo: images/colosseum.png + favicon: images/colosseum.png + features: + - content.tabs.link + - toc.follow + - navigation.indexes + - navigation.footer + - navigation.tabs + - navigation.tabs.sticky + - search.suggest + - search.highlight + - search.share + custom_dir: overrides + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference + +markdown_extensions: + # PyMdown Extensions + pymdownx.fancylists: {} # Supports various ordered list styles + pymdownx.highlight: {} # Highlights code blocks, when language provided. + pymdownx.inlinehilite: {} # Highlights inline code, when language provided. + pymdownx.keys: {} # Fancy displays key combinations. + pymdownx.superfences: {} # Nicer code-blocks. + pymdownx.saneheaders: {} # Treats "#Content" with no space at the beginning of a line as text, not a header; helpful with MagicLink. rumdl will still verify header formatting. + pymdownx.tasklist: {} # Make fancy checklists. + pymdownx.blocks.caption: {} # Captions images. + 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: # Enables tabbed content. + alternate_style: true + pymdownx.snippets: # Allows for injecting content from other locations. + base_path: ["docs"] + url_download: true + check_paths: true + pymdownx.magiclink: # Among other things, enables GitHub shorthand references. + provider: "github" + user: "beeware" + repo: "website" + repo_url_shortener: true + repo_url_shorthand: true + normalize_issue_symbols: true + # Python Markdown Extensions + attr_list: {} # Enables setting explicit anchors, and CSS classes, etc. + smarty: # Enables easy em and en dashes. + smart_quotes: false + toc: # Enables the ToC, in the left sidebar, in the documentation. + permalink: true + title: On this page + +plugins: + search: {} + 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: + include_dir: {} + mkdocstrings: + default_handler: python + handlers: + python: + paths: [src] + options: + docstring_style: sphinx # Parses docstrings from Sphinx formatting - the `:param` formatting, not parsing rST links + allow_inspection: false # True includes *more* dunder methods, can be enabled on individual class entries if you want them + show_source: false # Otherwise, source code is shown collapsed for all + members_order: alphabetical # Orders things based on the source code + annotations_path: brief # Keeps type annotation links more concise + merge_init_into_class: true # Otherwise, init is displayed separately + separate_signature: true # Shows the `function(args)` separately from name + show_signature: true # Displays () or (args) along with the function name in the signature + show_signature_annotations: true # Includes annotations in signature blocks + signature_crossrefs: true # Enables cross-referencing on signature annotations + show_root_heading: true # Show heading of object at root, otherwise nothing + docstring_section_style: spacy # Better info layout than the other options + line_length: 80 # Requires ruff, forces longer signatures to be stacked + show_symbol_type_toc: true # Enables type symbols next to objects in ToC + show_symbol_type_heading: true # Enables type symbols next to object names in content + show_attribute_values: false # Suppresses the values of attributes in the signature + heading_level: 3 # Heading level of 3 to nest under References heading diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md new file mode 100644 index 000000000..71d10bab9 --- /dev/null +++ b/docs/en/SUMMARY.md @@ -0,0 +1,52 @@ +--- +search: + exclude: true +--- + +- Tutorial + - [Tutorial](tutorial/index.md) +- How-to guides + - [How-to guides](how-to/index.md) + - Contribute + - [Contributing](how-to/contribute/index.md) + - [First-time contributors](how-to/contribute/first-time-contributors.md) + - What can I do? + - [Fix an issue](how-to/contribute/what/fix-issue.md) + - [Implement a new feature](how-to/contribute/what/implement-feature.md) + - [Write documentation](how-to/contribute/what/write-docs.md) + - [Triage an issue](how-to/contribute/what/triage.md) + - [Review a pull request](how-to/contribute/what/review-pr.md) + - [Propose a new feature](how-to/contribute/what/propose-feature.md) + - [Use the tools](how-to/contribute/what/use-tools.md) + - How do I contribute? + - [Setting up a development environment](how-to/contribute/how/dev-environment.md) + - [Reproducing an issue](how-to/contribute/how/reproduce-issue.md) + - [Working from a branch](how-to/contribute/how/branches.md) + - [Avoiding scope creep](how-to/contribute/how/scope-creep.md) + - [Writing, running, and testing code](how-to/contribute/how/write-code.md) + - [Building documentation](how-to/contribute/how/build-docs.md) + - [Writing documentation](how-to/contribute/how/write-docs.md) + - [Adding a change note](how-to/contribute/how/change-note.md) + - [Submitting a pull request](how-to/contribute/how/submit-pr.md) + - [Providing a review](how-to/contribute/how/review-pr.md) + - [Submitting a new issue](how-to/contribute/how/new-issue.md) + - [Proposing a new feature](how-to/contribute/how/propose-feature.md) + - What happens next? + - [Pull request review process](how-to/contribute/next/pr-review.md) + - [Release process](how-to/contribute/next/release.md) + - Policies + - [AI Policy](how-to/contribute/policies/ai-policy.md) + - Style guides + - [Code style guide](how-to/contribute/style/code-style-guide.md) + - [Documentation style guide](how-to/contribute/style/docs-style-guide.md) + - Internal + - [Internal How-to guides](how-to/internal/index.md) + - [Release process](how-to/internal/release.md) +- Topic guides + - [Topic guides](topics/index.md) +- Reference + - [Reference](reference/index.md) +- About Colosseum + - [About Colosseum](about/index.md) + - [FAQ](about/faq.md) + - [Release History](about/releases.md) diff --git a/docs/en/about/faq.md b/docs/en/about/faq.md new file mode 100644 index 000000000..7679aaaa1 --- /dev/null +++ b/docs/en/about/faq.md @@ -0,0 +1,15 @@ +# Frequently Asked Questions + +## So... why the name Colosseum? + +The Colosseum, also known as the Flavian Amphitheater, is an ancient Roman Amphitheater in the center of Rome. It is an astounding piece of ancient architecture, noted for it's three layers of arches, framed by Doric, Ionic and Corinthian half-columns, with an attic decorate with Corinthian pilasters. + +Much like Doric, Ionic and Corinthian columns form the fundamental architecture of the ancient Roman world, CSS is part of the fundamental architecture of modern display computing. The regular repeating structure of the Colosseum's arches and columns mirror the regular grid-based layout of many modern web and print designs. + +The Colosseum was also a massive undertaking for it's time. Undertaking to reproduce the entire CSS specification, with all it's quirks and eccentricities, is a similarly massive undertaking. + +But most importantly: the name Colosseum contains, in order, the letters CSS. + +## What version of Python does Colosseum support? + +Python 3.11 or higher. diff --git a/docs/en/about/index.md b/docs/en/about/index.md new file mode 100644 index 000000000..532627ac3 --- /dev/null +++ b/docs/en/about/index.md @@ -0,0 +1,6 @@ +# About Colosseum + +Want to know more about Colosseum? That's what you'll find here! + +- [Frequently asked questions](faq.md) - Answers to common questions about using Colosseum. +- [Release History](releases.md) - A list of changes made in each release. diff --git a/docs/background/releases.rst b/docs/en/about/releases.md similarity index 82% rename from docs/background/releases.rst rename to docs/en/about/releases.md index 883761bce..6b863afb7 100644 --- a/docs/background/releases.rst +++ b/docs/en/about/releases.md @@ -1,48 +1,40 @@ -=============== -Release History -=============== +# Release History + + .. towncrier release notes start -0.2.0 -===== +## 0.2.0 From scratch rewrite, using Travertino base classes. -v0.1.6 -====== +## 0.1.6 * Fixed the MANIFEST.in file. -v0.1.5 -====== +## 0.1.5 * Modify hints so that they only mark layout as modified if the value changes. -v0.1.4 -====== +## v0.1.4 * Made the dirty flag a tri-state variable, to allow for "layout in progress" tracking. -v0.1.3 -====== +## 0.1.3 * Added ability to extract absolute position of DOM nodes -v0.1.2 -====== +## 0.1.2 * Added first W3C-based test suite. * Added hinting for style objects. * Separated style definition from DOM definition. -v0.1.1 -====== +## 0.1.1 * Added protection against invalid values for string-based properties. * Added support for bulk setting of attributes. -v0.1.0 -====== +## 0.1.0 Initial release of a version based on a port of Facebook's CSS-layout (now `Yoga `__) project. diff --git a/docs/en/how-to/contribute/first-time-contributors.md b/docs/en/how-to/contribute/first-time-contributors.md new file mode 100644 index 000000000..ae96a20bd --- /dev/null +++ b/docs/en/how-to/contribute/first-time-contributors.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/first-time-contributors.md" %} diff --git a/docs/en/how-to/contribute/how/branches.md b/docs/en/how-to/contribute/how/branches.md new file mode 100644 index 000000000..96d7c7de0 --- /dev/null +++ b/docs/en/how-to/contribute/how/branches.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/branches.md" %} diff --git a/docs/en/how-to/contribute/how/build-docs.md b/docs/en/how-to/contribute/how/build-docs.md new file mode 100644 index 000000000..fff325606 --- /dev/null +++ b/docs/en/how-to/contribute/how/build-docs.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/build-docs.md" %} diff --git a/docs/en/how-to/contribute/how/change-note.md b/docs/en/how-to/contribute/how/change-note.md new file mode 100644 index 000000000..a1e7ff8dc --- /dev/null +++ b/docs/en/how-to/contribute/how/change-note.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/change-note.md" %} diff --git a/docs/en/how-to/contribute/how/dev-environment.md b/docs/en/how-to/contribute/how/dev-environment.md new file mode 100644 index 000000000..513596888 --- /dev/null +++ b/docs/en/how-to/contribute/how/dev-environment.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/dev-environment.md" %} diff --git a/docs/en/how-to/contribute/how/new-issue.md b/docs/en/how-to/contribute/how/new-issue.md new file mode 100644 index 000000000..5aff7df45 --- /dev/null +++ b/docs/en/how-to/contribute/how/new-issue.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/new-issue.md" %} diff --git a/docs/en/how-to/contribute/how/propose-feature.md b/docs/en/how-to/contribute/how/propose-feature.md new file mode 100644 index 000000000..b9fb4e852 --- /dev/null +++ b/docs/en/how-to/contribute/how/propose-feature.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/propose-feature.md" %} diff --git a/docs/en/how-to/contribute/how/reproduce-issue.md b/docs/en/how-to/contribute/how/reproduce-issue.md new file mode 100644 index 000000000..2dab7783f --- /dev/null +++ b/docs/en/how-to/contribute/how/reproduce-issue.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/reproduce-issue.md" %} diff --git a/docs/en/how-to/contribute/how/review-pr.md b/docs/en/how-to/contribute/how/review-pr.md new file mode 100644 index 000000000..6d26605c1 --- /dev/null +++ b/docs/en/how-to/contribute/how/review-pr.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/review-pr.md" %} diff --git a/docs/en/how-to/contribute/how/scope-creep.md b/docs/en/how-to/contribute/how/scope-creep.md new file mode 100644 index 000000000..89fddd784 --- /dev/null +++ b/docs/en/how-to/contribute/how/scope-creep.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/scope-creep.md" %} diff --git a/docs/en/how-to/contribute/how/submit-pr.md b/docs/en/how-to/contribute/how/submit-pr.md new file mode 100644 index 000000000..d4eee58e3 --- /dev/null +++ b/docs/en/how-to/contribute/how/submit-pr.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/submit-pr.md" %} diff --git a/docs/en/how-to/contribute/how/write-code.md b/docs/en/how-to/contribute/how/write-code.md new file mode 100644 index 000000000..df21be275 --- /dev/null +++ b/docs/en/how-to/contribute/how/write-code.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/write-code.md" %} diff --git a/docs/en/how-to/contribute/how/write-docs.md b/docs/en/how-to/contribute/how/write-docs.md new file mode 100644 index 000000000..26472c2f3 --- /dev/null +++ b/docs/en/how-to/contribute/how/write-docs.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/how/write-docs.md" %} diff --git a/docs/en/how-to/contribute/index.md b/docs/en/how-to/contribute/index.md new file mode 100644 index 000000000..e828b1f1a --- /dev/null +++ b/docs/en/how-to/contribute/index.md @@ -0,0 +1,3 @@ +# Contributing to {{ formal_name }} + +{% extends "_shared/contribute/index.md" %} diff --git a/docs/en/how-to/contribute/next/pr-review.md b/docs/en/how-to/contribute/next/pr-review.md new file mode 100644 index 000000000..110e5d6c9 --- /dev/null +++ b/docs/en/how-to/contribute/next/pr-review.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/next/pr-review.md" %} diff --git a/docs/en/how-to/contribute/next/release.md b/docs/en/how-to/contribute/next/release.md new file mode 100644 index 000000000..64783cdfb --- /dev/null +++ b/docs/en/how-to/contribute/next/release.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/next/release.md" %} diff --git a/docs/en/how-to/contribute/policies/ai-policy.md b/docs/en/how-to/contribute/policies/ai-policy.md new file mode 100644 index 000000000..43bdffca5 --- /dev/null +++ b/docs/en/how-to/contribute/policies/ai-policy.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/policies/ai-policy.md" %} diff --git a/docs/en/how-to/contribute/style/code-style-guide.md b/docs/en/how-to/contribute/style/code-style-guide.md new file mode 100644 index 000000000..b3e7829df --- /dev/null +++ b/docs/en/how-to/contribute/style/code-style-guide.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/style/code-style-guide.md" %} diff --git a/docs/en/how-to/contribute/style/docs-style-guide.md b/docs/en/how-to/contribute/style/docs-style-guide.md new file mode 100644 index 000000000..cf4f23e3a --- /dev/null +++ b/docs/en/how-to/contribute/style/docs-style-guide.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/style/docs-style-guide.md" %} diff --git a/docs/en/how-to/contribute/what/fix-issue.md b/docs/en/how-to/contribute/what/fix-issue.md new file mode 100644 index 000000000..d2009be92 --- /dev/null +++ b/docs/en/how-to/contribute/what/fix-issue.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/what/fix-issue.md" %} diff --git a/docs/en/how-to/contribute/what/implement-feature.md b/docs/en/how-to/contribute/what/implement-feature.md new file mode 100644 index 000000000..f37e86793 --- /dev/null +++ b/docs/en/how-to/contribute/what/implement-feature.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/what/implement-feature.md" %} diff --git a/docs/en/how-to/contribute/what/propose-feature.md b/docs/en/how-to/contribute/what/propose-feature.md new file mode 100644 index 000000000..47f832f87 --- /dev/null +++ b/docs/en/how-to/contribute/what/propose-feature.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/what/propose-feature.md" %} diff --git a/docs/en/how-to/contribute/what/review-pr.md b/docs/en/how-to/contribute/what/review-pr.md new file mode 100644 index 000000000..c75df4038 --- /dev/null +++ b/docs/en/how-to/contribute/what/review-pr.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/what/review-pr.md" %} diff --git a/docs/en/how-to/contribute/what/triage.md b/docs/en/how-to/contribute/what/triage.md new file mode 100644 index 000000000..365deb489 --- /dev/null +++ b/docs/en/how-to/contribute/what/triage.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/what/triage.md" %} diff --git a/docs/en/how-to/contribute/what/use-tools.md b/docs/en/how-to/contribute/what/use-tools.md new file mode 100644 index 000000000..a01a96bae --- /dev/null +++ b/docs/en/how-to/contribute/what/use-tools.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/what/use-tools.md" %} diff --git a/docs/en/how-to/contribute/what/write-docs.md b/docs/en/how-to/contribute/what/write-docs.md new file mode 100644 index 000000000..dcf508835 --- /dev/null +++ b/docs/en/how-to/contribute/what/write-docs.md @@ -0,0 +1 @@ +{% extends "_shared/contribute/what/write-docs.md" %} diff --git a/docs/en/how-to/index.md b/docs/en/how-to/index.md new file mode 100644 index 000000000..44c7f8e1a --- /dev/null +++ b/docs/en/how-to/index.md @@ -0,0 +1,15 @@ +# How-to guides + +How-to guides are recipes that take you through the steps involved in addressing key problems and use cases. They are more advanced than tutorials and assume some knowledge of how Colosseum works. + +## Contributing to Colosseum + +The many ways you can contribute to Colosseum, including what you can do and how to do it. + +- [Contributing to Colosseum](contribute/index.md) + +## Internal guides + +Guides for the maintainers of Colosseum, documenting internal project procedures. + +- [How to cut a Colosseum release](internal/release.md) diff --git a/docs/en/how-to/internal/index.md b/docs/en/how-to/internal/index.md new file mode 100644 index 000000000..bf87a5409 --- /dev/null +++ b/docs/en/how-to/internal/index.md @@ -0,0 +1,5 @@ +# Colosseum internal How-to guides + +These guides are for the maintainers of the Colosseum project, documenting internal project procedures. + +- [How to cut a Colosseum release](release.md) diff --git a/docs/en/how-to/internal/release.md b/docs/en/how-to/internal/release.md new file mode 100644 index 000000000..669407127 --- /dev/null +++ b/docs/en/how-to/internal/release.md @@ -0,0 +1,62 @@ +# How to cut a Colosseum release + +The release infrastructure for Colosseum is semi-automated, using GitHub Actions to formally publish releases. + +This guide assumes that you have an `upstream` remote configured on your local clone of the Colosseum repository, pointing at the official repository. If all you have is a checkout of a personal fork of the Colosseum repository, you can configure that checkout by running: + +```bash +git remote add upstream https://github.com/beeware/colosseum.git +``` + +The procedure for cutting a new release is as follows: + +1. Check the contents of the upstream repository's main branch: + + ```bash + git fetch upstream + git checkout --detach upstream/main + ``` + + Check that the HEAD of release now matches upstream/main. + +2. Make sure the branch is ready for release. Ensure that: + + 1. The version number has been bumped. + + 2. The release notes are up to date. If they are, the [changes](https://github.com/beeware/colosseum/tree/main/changes) directory should be empty, except for the `template.rst` file. + + These two changes (the version bump and release notes update) should go through the normal pull request and review process. They should generally comprise the last PR merged before the release occurs. + + If the version number *hasn't* been updated, or `changes` directory *isn't* empty, you need to create a PR (using the normal development process) that contains these changes. Run: + + ```bash + tox -e towncrier -- --draft + ``` + + to review the release notes that will be included, and then: + + ```bash + tox -e towncrier + ``` + + to generate the updated release notes. Submit the PR; once it's been reviewed and merged, you can restart the release process from step 1. + +3. Tag the release, and push the tag upstream: + + ```bash + git tag v1.2.3 + git push upstream main + git push upstream v1.2.3 + ``` + +4. Pushing the tag will start a workflow to create a draft release on GitHub. You can [follow the progress of the workflow on GitHub](https://github.com/beeware/colosseum/actions?query=workflow%3A%22Create+Release%22); once the workflow completes, there should be a new [draft release](https://github.com/beeware/colosseum/releases). + +5. Edit the GitHub release. Add release notes (you can use the text generated by towncrier). Check the pre-release checkbox (if necessary). + +6. Double check everything, then click Publish. This will trigger a [publication workflow on GitHub](https://github.com/beeware/colosseum/actions?query=workflow%3A%22Upload+Python+Package%22). + +7. Wait for the [package to appear on PyPI](https://pypi.org/project/colosseum/). + +Congratulations, you've just published a release! + +If anything went wrong during steps 3 or 5, you will need to delete the draft release from GitHub, and push an updated tag. Once the release has successfully appeared on PyPI, it cannot be changed; if you spot a problem in a published package, you'll need to tag a completely new release. diff --git a/docs/_static/images/colosseum.png b/docs/en/images/colosseum.png similarity index 100% rename from docs/_static/images/colosseum.png rename to docs/en/images/colosseum.png diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 000000000..67f7c69aa --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,32 @@ +# Colosseum + +Colosseum is an independent implementation of the CSS layout algorithm. This implementation is completely standalone - it isn't dependent on a browser, and can be run over any box-like set of objects that need to be laid out on a page (either physical or virtual). + +## [Tutorial](tutorial/index.md) + +Get started with a hands-on introduction to Colosseum for beginners. + +## [How-to guides](how-to/index.md) + +Guides and recipes for common problems and tasks, including how to contribute to Colosseum. + +## [Topic guides](topics/index.md) + +Deeper explorations of concepts and issues related to Colosseum. + +## [Reference](reference/index.md) + +Technical reference for the public API provided by Colosseum. + +## [About Colosseum](about/index.md) + +Frequently asked questions, community resources, and release history. + +## Community + +Colosseum 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/). diff --git a/docs/en/reference/index.md b/docs/en/reference/index.md new file mode 100644 index 000000000..1826d4e70 --- /dev/null +++ b/docs/en/reference/index.md @@ -0,0 +1,3 @@ +# Reference + +This is the technical reference for the public API provided by Colosseum diff --git a/docs/en/topics/index.md b/docs/en/topics/index.md new file mode 100644 index 000000000..56eca7a70 --- /dev/null +++ b/docs/en/topics/index.md @@ -0,0 +1,3 @@ +# Topic guides + +Coming soon... diff --git a/docs/en/tutorial/index.md b/docs/en/tutorial/index.md new file mode 100644 index 000000000..c55b65b2d --- /dev/null +++ b/docs/en/tutorial/index.md @@ -0,0 +1,3 @@ +# Tutorial + +Coming soon... diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst deleted file mode 100644 index 4fb16f47e..000000000 --- a/docs/how-to/contribute.rst +++ /dev/null @@ -1,463 +0,0 @@ -.. _contribute: - -============================== -How to contribute to Colosseum -============================== - -This guide will help walk you through the process of contributing your first -contribution to Colosseum. - -Set up your development environment -=================================== - -Go to the `Colosseum repository on GitHub `__, -and fork the repository into your own Github account. - -Then, you need to set up your development environment. To work on Colosseum, you'll need Python 3.4+ installed on your computer. Create a virtual environment, and clone your Colosseum -fork:: - - $ mkdir beeware - $ cd beeware - $ python3 -m venv venv - $ source venv/bin/activate - $ git clone git@github.com:/colosseum.git - $ cd colosseum - -You can then run the test suite:: - - $ python setup.py test - -This will run around 2300 tests - most of which are currently marked as -"expected failures". This means that we have the test, but we *know* that -they're failing at the moment, for reasons that we understand -- usually, that -we just haven't implemented the section of the CSS specification that the test -is exercising. - -You shouldn't *ever* get any **FAIL** or **ERROR** test results. We run our -full test suite before merging every patch. If that process discovers any -problems, we don't merge the patch. If you *do* find a test error or failure, -either there's something odd in your test environment, or you've found an edge -case that we haven't seen before - either way, let us know! - -Now you are ready to start hacking on Colosseum. Have fun! - -What should I do? -================= - -Having run the test suite, you now know which tests are currently expected -failures. Your task is to take one of these tests, and make whatever -modifications are necessary to get that test into a passing state, without -breaking any other tests. - -About the test suite --------------------- - -The bulk of Colosseum's test suite is automatically generated based on the -W3C's `Web Platform Tests `__. -This is the canonical test suite for W3C standard compliance. - -Unfortunately, this test suite is very browser centric, and isn't an automated -test suite. It relies on a human loading a series of web pages, and comparing -each page against a reference rendering. This is necessary in a web context, -because browsers are allowed to have minor variations in rendering. However, -it's a problem for Colosseum, for two reasons: firstly, because we want a -fully automated test suite; but also because we're not targeting a web -browser, so "load this web page" isn't a test we can use. - -So - Colosseum's ``utils`` directory has a set of scripts that take the W3C -repository, and converts each page into raw data. It uses `Toga -`__ to create a 640x480 web view, loads the test -document, and then injects some Javascript to extract the document structure -and the rendering information about the document. - -The output of this process is two documents - a `data` file, and a -`reference` file. - -The `data` file contains a JSON-formatted version of the DOM elements in the -test, with their style declarations. - -The `reference` file contains the same DOM structure - but instead of -recording the style, it records the size, position, borders, padding and -margin of each element in the DOM. - -The test suite takes the data file, reconstructs the DOM nodes in Colosseum, -and apply the test styles to those nodes. It then lays out the document, and -evaluates if the size and position of each DOM node in the document matches -that in the reference rendering. - -Effectively, what we're doing is checking that given the same inputs, -Colosseum will produce the same output as the web view - except that we don't -ever have to draw anything on a screen. We're checking the layout at a basic -mathematical level. - -Of course, this assumes that the webview that was used to render the document -is, itself, correct. The test suite was generated on a Mac using a Safari 11 -Webkit webview, so the CSS2 components **should** be fully compliant; however, -some CSS3 tests (especially in the flexbox and grid modules) may be incorrect. - -Picking a test --------------- - -All the tests are located under the tests directory. Each test directory contains -a ``not_implemented`` file. This is a list of tests that are currently known to -fail - because the logic necessary to make the test pass isn't implemented. -Pick one of these tests, and delete it from the ``not_implemented`` file. - -For the purposes of this example, we're going to pick the -``block-formatting-contexts-006`` test in ``web_platform/CSS2/normal_flow/test_block_formatting_contexts`` (this test is no longer available, as it has already been fixed). - -The first test run ------------------- - -Each test file contains a single test class. In order to run the test, you must specify -the path to this class, separated by dots. For our example, you can run the single test -out of the test suite:: - - $ python setup.py test -s tests.web_platform.CSS2.normal_flow.test_block_formatting_contexts.TestBlockFormattingContexts.test_block_formatting_contexts_006 - -This will produce a lot of console output. This output will start with some -lines that tells you that the test is being set up and run:: - - running test - running egg_info - writing dependency_links to colosseum.egg-info/dependency_links.txt - writing colosseum.egg-info/PKG-INFO - writing top-level names to colosseum.egg-info/top_level.txt - reading manifest file 'colosseum.egg-info/SOURCES.txt' - reading manifest template 'MANIFEST.in' - writing manifest file 'colosseum.egg-info/SOURCES.txt' - running build_ext - -Then, it will output the name of the test being executed, and whether it -passed or failed:: - - test_block_formatting_contexts_006 (tests.web_platform.CSS2.normal_flow.test_block_formatting_contexts.TestBlockFormattingContexts) - When there is no padding or margins on elements the right outer edge of the child box will touch the right edge of the containing block. ... FAIL - -It then gives you a detailed description of **why** the test failed:: - - ====================================================================== - FAIL: test_block_formatting_contexts_006 (tests.web_platform.CSS2.normal_flow.test_block_formatting_contexts.TestBlockFormattingContexts) - When there is no padding or margins on elements the right outer edge of the child box will touch the right edge of the containing block. - ---------------------------------------------------------------------- - -This description comes from the W3C test suite - it might point you in the -right direction, or it might not. - -You'll then see the stack trace at the point the test failed:: - - Traceback (most recent call last): - File "/Users/rkm/projects/beeware/colosseum/tests/utils.py", line 360, in test_method - '\n' + '\n'.join(extra) - File "/Users/rkm/projects/beeware/colosseum/tests/utils.py", line 277, in assertLayout - self.fail('\n'.join(output)) - AssertionError: - -This will tell you the line of code where the test failed. However, as our -test is automatically generated, this won't really tell you much, other than -the fact that the test generation code is all in ``tests/utils.py``. - -What *is* helpful is the next piece of output:: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * 624x96 @ (8, 8) - padding: 624x96 @ (8, 8) - border: 624x96 @ (8, 8) - *
96x96 @ (8, 8) - padding: 96x96 @ (8, 8) - border: 101x96 @ (8, 8) - *
91x96 @ (8, 8) - padding: 91x96 @ (8, 8) - >> padding: 96x96 @ (8, 8) - border: 96x96 @ (8, 8) - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is a comparison between what was generated by Colosseum, and what was -expected. In this example, the two documents are almost identical, except for -the padding box of one element. Colosseum has determined that the padding box -is 96 pixels wide (the line indicated with the ``>>`` marker); the reference -rendering says it should be 91 pixels wide. - -The test output then gives us some pointers for where to look in the standard -for the rules that need to be followed:: - - See http://www.w3.org/TR/CSS21/visuren.html#block-formatting - -and the W3C test itself:: - - Test: http://test.csswg.org/harness/test/css21_dev/single/block-formatting-contexts-006/ - -lastly, as the test shuts down, we get some summary output for the test run:: - - ---------------------------------------------------------------------- - Ran 1 test in 0.005s - - FAILED (failures=1) - Test failed: - error: Test failed: - -This example shows a case where the code is running to completion without -error, but is generating incorrect output. It's also possible that you might -see errors caused when the code cannot run to completion. For example, in the -following case, a ``None`` value has mistaken leaked into a padding box -calculation:: - - File "/Users/rkm/projects/beeware/colosseum/colosseum/dimensions.py", line 594, in padding_box_width - return self._padding_left + self._content_width + self._padding_right - - TypeError: unsupported operand type(s) for +: 'int' and 'NoneType' - -You may also see exceptions that are raised specifically mentioning parts of -the CSS specification that have not yet been implmemented. For example, this -exception would be raised if the layout example requires the rules of Section -9.4.2 of the CSS2.2 specification, but that section hasn't been implemented:: - - File "/Users/rkm/projects/beeware/colosseum/colosseum/engine.py", line 239, in layout_box - raise NotImplementedError("Section 9.4.2 - relative positioning") # pragma: no cover - - NotImplementedError: Section 9.4.2 - relative positioning - -Lastly, you might see errors where the rendering engine has become confused. -In this example, a impossible branch of code has been reached while -calculating a width of an element in normal flow:: - - File "/Users/rkm/projects/beeware/colosseum/colosseum/engine.py", line 284, in calculate_width_and_margins - raise Exception("Unknown normal flow width calculation") # pragma: no cover - - Exception: Unknown normal flow width calculation - -Ok! So we now have a failing test. What do we do about it? - -Is the test case correct? -------------------------- - -Since the test suite is automatically generated, and there are over 2000 -tests, we can't be 100% certain that the test *itself* is correct. So - we -need to confirm whether the test itself is valid. - -Click on the link `to the W3C test -`__ that was in the test output. You should see a page that looks something like: - -.. image:: screenshots/w3c-test-suite.png - -Using this view, confirm that the test acutally passes. In this case, the page -tells us to compare to the reference page; you can flick between the "Test -Case" tab and the "Reference Page" tab and confirm that the output is as -expected. - -.. note:: - - Many of the tests in the test suite use a special font, called "Ahem". - Ahem is a font that has a limited character set, but known (and simple) - geometries for each character - for example, the M glyph (used to - establish the size of the "em" unit) is a solid black square. This helps - make test results repeatable. You'll need to `install this font - `__ before confirming the - output of any test that uses it. - -The reference rendering won't always be pixel perfect, so you'll need to check -any text on the page to see whether the test is passing in the browser. - -If the test appears to be failing, then there's no point trying to reproduce -the browser's behavior in Colosseum! Look for a file called ``not_compliant`` -in the same directory as the ``not_implemented`` file. If this file doesn't -exist - create it. Then, add to the `not_compliant` file the same line that -you *deleted* from ``not_implemented``. Rerun the test - it should come back -reporting as an expected failure:: - - running test - running egg_info - writing colosseum.egg-info/PKG-INFO - writing top-level names to colosseum.egg-info/top_level.txt - writing dependency_links to colosseum.egg-info/dependency_links.txt - reading manifest file 'colosseum.egg-info/SOURCES.txt' - reading manifest template 'MANIFEST.in' - writing manifest file 'colosseum.egg-info/SOURCES.txt' - running build_ext - test_block_formatting_contexts_006 (tests.web_platform.CSS2.normal_flow.test_block_formatting_contexts.TestBlockFormattingContexts) - When there is no padding or margins on elements the right outer edge of the child box will touch the right edge of the containing block. ... expected failure - - ---------------------------------------------------------------------- - Ran 1 test in 0.004s - - OK (expected failures=1) - -And you're done! You've just told the test suite that yes, the test will fail, -but because the Webkit test result isn't correct. - -.. note:: - - Most of the tests in the CSS test suite *should* pass. If you think you've - found a failure in a CSS2 test, you should try and confirm with others - before you submit your patch. You may find the `W3C's test results - `__ helpful - these are - results reported by other users. - -Sometimes, the test will pass, but it will be validating something that -Colosseum is not concerned with. For example, some of the tests deal with -behavior during DOM manipulation (insertion or removal of elements from the -DOM with JavaScript). DOM manipulation isn't something Colosseum is trying to -model, so this test isn't of any use to us. In this case, you should move the -test line from the ``not_implemented`` file to the ``not_valid`` file (again, -you may need to create this file if it doesn't exist). This flags that it is a -test that doesn't need to be executed at all. - -If you find an invalid or non-compliant test, submit a pull request for the -change moving the line out of the ``not_implemented`` file, and you're done! -That pull request should detail *why* you believe the test in invalid, so that -the person reviewing your pull request understands your reasoning. You can now -pick another test, and work on your second pull request! - -However, if the test passes, the next step is to try and fix it. - -.. note:: - - If you're a newcomer to Colosseum, and the test you've chosen involves - rendering text, displaying an image, or testing the color of an element - (other than where color is used purely to make an element visible), you - might want pick another test to work on. The easiest tests to work on will - involve the positioning of boxes on a page, without any images or text. - -The raw test ------------- - -Near the top of the test suite page, there is a "Test Case:" label, followed -by two links. These are links to the raw documents that are used in the test. -If you click on the first link (the test document), you'll see a page that -looks just like the test case, but without the test harness around it: - -.. image:: screenshots/w3c-test-suite-raw.png - -In this test, the raw test page is a line of test instructions. This won't -exist on every test case; but if it *does* exist, we need to strip it out to -simplify the test for our purposes. Open the web inspector, select the ``

`` -element corresponding to the test instruction: - -.. image:: screenshots/w3c-test-suite-raw-editor.png - -Right click on the element, and select "Delete element". This will remove the -instruction from the page: - -.. image:: screenshots/w3c-test-suite-cleaned.png - -.. note:: - - Sometimes, the test instruction *is* the test - for example, the test - might read "This text should not be red". If this is the case, you - *shouldn't* delete the instructional text. You only delete the - instructional text if it is *purely* instructional - if it doesn't - actually participate in the layout being tested. - -Once you've deleted - for example, in the screenshot, you can see that the -``

`` element that is the child of the ```` should have a content size -of 96x96, and a right border of 5 pixels. We can compare this to the output -produced when we ran our test, and see that yes - during the test, the border -box was 101x96, the inner content was 96x96, but both the border box and the -inner content of that element had an origin of 8x8. This means the right -border extended 5 pixels past the content. - -We can now start digging into the code to see if we can identify why the -margin box hasn't received the correct size. - -Fixing the problem ------------------- - -At this point, you're in bug country! Every bug will have a slightly -different cause, and it's your job to find out what is going on. - -The entry point for rendering is the ``layout()`` method in -``src/colosseum/engine.py``. This method calls ``layout_box()`` recursively on the -document being rendered. The code in ``src/colosseum/engine.py`` is extensively -documented with references to the `CSS specification -`__ - especially the `CSS2.2 Specification -`__, the `Flexible Box Layout Module -`__, and the `Grid Layout Module -`__. Any changes you make should be -include equally verbose documentation, and cross references to any paragraphs -in the specification. - -The test suite uses a ``ExampleNode`` as the basis for it's document model. A -test node has three attributes of particular interest: - - * ``style``, storing the CSS style declaration that applies to the node. - These values may be expressed in any units allowed by CSS (including - pixels, points, em, percent, and more). The sub-attributes of the ``style`` - attribute match those of the CSS specification (e.g., ``width``, - ``margin_top``, ``z_index``, and so on). - - * ``layout``, storing the computed values for the layout of the ExampleNode. - These values are *always* in integer pixels. The layout describes the - position of a content box (defined by ``content_top``, ``content_right``, - ``content_bottom`` and ``content_left``), relative to the content box of - it's parent (with an offset defined by ``offset_top`` and ``offset_left``). - Surrounding the content box is a padding box, surrounded by a border box, - surrounded by a margin box. These are also given in pixels, relative to - the content box of the parent element. - - * ``children``, a list of ExampleNodes that are descendents of this node. A - leaf node in the DOM tree is a node with an empty children list. - -The layout algorithm roughly consists of: - - 1. Set up and copy over initial layout values by computing the style - values. - - 2. Calculate the width of the node - - 3. Iterate over the children of the node - - 4. Calulate the height of the node - - 5. Make an adjustments for relative positioning. - -Dig into the code, and work out why Colosseum is giving the wrong result. - -Re-run the test suite ---------------------- - -Once you've identified the problem, and the single test passes, you can re-run -the *entire* Colosseum test suite. One of three things will happen: - - 1. The test suite will pass without any errors. In this case, you've fixed - exactly one bug. Submit a pull request with your fix, and try another one! - - 2. The test suite will report one or more FAIL or ERROR results. In this - case, you've fixed one bug, but broken existing behavior in the process. - This means there's something subtle wrong with your fix. Go back to the - code, and see if you can find a way to make your chosen test pass - *without* breaking other tests. - - 3. The test suite will report one or more UNEXPECTED PASS results. This is - good news - it means that the fix you've made has indirectly fixed one - more more *other* tests! Quickly verify that those tests are valid (using - the same process that you used to verify the test you *deliberately* - fixed), and if they're valid tests, remove them from the ``not_implemented`` - file. Submit a pull request with your fix, and try another one! - -What if the test itself is incorrect? -------------------------------------- - -Since the reference test data is automatically extracted from a running -browser, and browsers don't provide a great API for extracting rendering data, -it's entirely possible that the reference test data that the test is using -might be incorrect. If you look at the test suite output, and it doesn't match -what you see in a browser, open a ticket describing what you've found. This -may indicate a bug in the reference rendering; which will require a fix to the -script that generates the test data. - -Add change information for release notes -======================================== - -Colosseum uses `towncrier `__ to automate -building release notes. To support this, every pull request needs to have a -corresponding file in the ``changes/`` directory that provides a short -description of the change implemented by the pull request. - -This description should be a high level summary of the change from the -perspective of the user, not a deep technical description or implementation -detail. It should also be written in past tense (i.e., "Added an option to -enable X" or "Fixed handling of Y"). - -See `News Fragments `__ -for more details on the types of news fragments you can add. You can also see -existing examples of news fragments in the ``changes/`` folder. diff --git a/docs/how-to/get-started.rst b/docs/how-to/get-started.rst deleted file mode 100644 index 24c6073a6..000000000 --- a/docs/how-to/get-started.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _get-started: - -================== -How to get started -================== - -To use Colosseum, create a new virtual environment, and install it:: - - $ python3 -m venv venv - $ source venv/bin/activate.sh - (venv) $ pip install colosseum - -You're now ready to use Colosseum! Your next step is to work through the -:ref:`tutorial`, which will take you step-by-step through your first steps -and introduce you to the important concepts you need to become familiar -with. diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst deleted file mode 100644 index 30798f878..000000000 --- a/docs/how-to/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _how-to: - -============= -How-to Guides -============= - -How-to guides are recipes that take the user through steps in key subjects. They are more advanced than tutorials and assume a lot more about what the user already knows than tutorials do, and unlike documents in the tutorial they can stand alone. - -.. toctree:: - :maxdepth: 1 - :glob: - - get-started - contribute diff --git a/docs/how-to/screenshots/w3c-test-suite-cleaned.png b/docs/how-to/screenshots/w3c-test-suite-cleaned.png deleted file mode 100644 index 8f8fc6cd9..000000000 Binary files a/docs/how-to/screenshots/w3c-test-suite-cleaned.png and /dev/null differ diff --git a/docs/how-to/screenshots/w3c-test-suite-raw-editor.png b/docs/how-to/screenshots/w3c-test-suite-raw-editor.png deleted file mode 100644 index a02930c28..000000000 Binary files a/docs/how-to/screenshots/w3c-test-suite-raw-editor.png and /dev/null differ diff --git a/docs/how-to/screenshots/w3c-test-suite-raw.png b/docs/how-to/screenshots/w3c-test-suite-raw.png deleted file mode 100644 index 91a904b92..000000000 Binary files a/docs/how-to/screenshots/w3c-test-suite-raw.png and /dev/null differ diff --git a/docs/how-to/screenshots/w3c-test-suite.png b/docs/how-to/screenshots/w3c-test-suite.png deleted file mode 100644 index c5d24ee39..000000000 Binary files a/docs/how-to/screenshots/w3c-test-suite.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 7194ff758..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. raw:: html - - - - -========= -Colosseum -========= - -Colosseum is an independent implementation of the CSS layout algorithm. This -implementation is completely standalone - it isn't dependent on -a browser, and can be run over any box-like set of objects that -need to be laid out on a page (either physical or virtual) - -.. rst-class:: row - -Table of contents -================= - -.. rst-class:: clearfix row - -.. rst-class:: column column2 - -:ref:`Tutorial ` --------------------------- - -Get started with a hands-on introduction for beginners - - -.. rst-class:: column column2 - -:ref:`How-to guides ` ------------------------------ - -Guides and recipes for common problems and tasks, including how to contribute - - -.. rst-class:: column column2 - -:ref:`Background ` ------------------------------- - -Explanation and discussion of key topics and concepts - - -.. rst-class:: column column2 - -:ref:`Reference ` ----------------------------- - -Technical reference - commands, modules, classes, methods - - -.. rst-class:: clearfix row - -Community -========= - -Colosseum is part of the `BeeWare suite`_. You can talk to the community through: - -* `@beeware@fosstodon.org on Mastodon`_ -* `Discord`_ -* The Colosseum `Github Discussions forum`_ - -We foster a welcoming and respectful community as described in our -`BeeWare Community Code of Conduct`_. - -.. _BeeWare suite: http://pybee.org -.. _Read The Docs: https://colosseum.readthedocs.io -.. _@beeware@fosstodon.org on Mastodon: https://fosstodon.org/@beeware -.. _Discord: https://beeware.org/bee/chat/ -.. _Github Discussions forum: https://github.com/beeware/colosseum/discussions -.. _BeeWare Community Code of Conduct: http://beeware.org/community/behavior/ - - -.. toctree:: - :maxdepth: 2 - :hidden: - :titlesonly: - - tutorial/index - how-to/index - background/index - reference/index diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 11247e197..000000000 --- a/docs/make.bat +++ /dev/null @@ -1,190 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -set I18NSPHINXOPTS=%SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Trebuchet.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Trebuchet.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end diff --git a/docs/mkdocs.en.yml b/docs/mkdocs.en.yml new file mode 100644 index 000000000..6c9e1aac4 --- /dev/null +++ b/docs/mkdocs.en.yml @@ -0,0 +1,11 @@ +INHERIT: config.yml +site_name: Colosseum +site_url: !ENV READTHEDOCS_CANONICAL_URL +docs_dir: en + +theme: + language: en + +extra: + translation_type: original + header: {} diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index 75327760f..000000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _reference: - -================ -Reference -================ - -.. toctree:: - :maxdepth: 1 - -This is the technical reference for public APIs provided by Colosseum. diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index a5f7db0e6..49a98d56c 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -1,21 +1,9 @@ -Alea BeeWare -callables -Est -Iacta -iOS -macOS -metaclasses -Objective-C -readonly -Roadmap -subclassed -subclassing - -# Usernames -Dayof -jeamland -Longhanks -ojii -stsievert -uranusjr +Corinthian +DOM +Flavian +pre +PyPI +towncrier +Travertino +tri diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst deleted file mode 100644 index ae00ac4c9..000000000 --- a/docs/tutorial/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _tutorial: - -========= -Tutorials -========= - -These tutorials are step-by step guides for using Colosseum. - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - tutorial-1 diff --git a/docs/tutorial/tutorial-1.rst b/docs/tutorial/tutorial-1.rst deleted file mode 100644 index 8af731fbc..000000000 --- a/docs/tutorial/tutorial-1.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _tutorial-1: - -=========================== -Your first Colosseum layout -=========================== - -In a virtualenv, install Colosseum:: - - $ pip install colosseum - -Colosseum provides a ``CSS`` class that allows you to define CSS properties and -apply them to any DOM-like tree of objects. There is no required base class; -Colosseum will duck-type any object providing the required API. The simplest -possible DOM node is the following:: - - from colosseum.dimensions import Size, Box - - class MyDOMNode: - def __init__(self, style): - self.parent = None - self.children = [] - self.intrinsic = Size(self) - self.layout = Box(self) - self.style = style.copy(self) - - def add(self, child): - self.children.append(child) - child.parent = self - - -That is, a node must provide: - -* a ``parent`` attribute, declaring the parent in the DOM tree; the root - of the DOM tree has a ``parent`` of ``None``. - -* a ``children`` attribute, containing the list of DOM child nodes. - -* an ``intrinsic`` attribute, storing any intrinsic size hints for the node. - -* a ``layout`` attribute, for storing the final position of the node. - -* a ``style`` attribute - generally a ``CSS`` declaration, bound to the node. - -We also need an area on to which we're going to render. This could be a screen, -a page, a canvas, or any other rectangular content area. Again, colosseum will -duck-type any class that has the required API:: - - class Page: - def __init__(self, width, height): - self.content_width = width - self.content_height = height - - -With a compliant DOM node definition, you can create a content page, an -instance of the DOM node class, and some children for that node:: - - >>> from colosseum import CSS - >>> from colosseum.constants import BLOCK - >>> page = Page(2000, 2000) - >>> node = MyDOMNode(style=CSS(display=BLOCK, width=1000, height=1000)) - >>> node.add(MyDOMNode(style=CSS(display=BLOCK, width=100, height=200))) - >>> node.add(MyDOMNode(style=CSS(display=BLOCK, width=300, height=150))) - -You can then ask for a layout to be computed, and query the results:: - - >>> from colosseum.engine import layout - >>> layout(page, node) - >>> print(node.layout) - - >>> node.layout.content_width - 1000 - >>> node.layout.content_height - 2000 - >>> node.layout.content_top - 0 - >>> node.layout.content_left - 0 - >>> for child in node.children: - ... print(child.layout) - - - -Note that although the root node specifies a height of 1000, the computed -content size is 2000 (i.e., the size of the display area). This matches how -the root element is sized in a HTML5 document. - -Style attributes can also be set in bulk, using the ``update()`` method on -the style attribute:: - - >>> node.style.update(width=1500, height=800) - >>> layout(page, node) - >>> print(node.layout) - - -Style attributes can also be removed by deleting the attribute on the -style attribute. The value of the property will revert to the default:: - - >>> node.style.update(margin_top=10, margin_left=20) - >>> layout(page, node) - >>> print(node.layout) - - >>> del(node.style.margin_left) - >>> layout(page, node) - >>> print(node.style.margin_left) - 0px - >>> print(node.layout) - diff --git a/pyproject.toml b/pyproject.toml index 2e844da4a..9d6d2d0f6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,8 +10,9 @@ dynamic = ["version"] name = "colosseum" description = "An independent implementation of the CSS layout algorithm" readme = "README.md" -requires-python = ">= 3.10" -license.text = "New BSD" +requires-python = ">= 3.11" +license = "BSD-3-Clause" +license-files = ["LICENSE"] authors = [ {name="Russell Keith-Magee", email="russell@keith-magee.com"} ] @@ -24,7 +25,6 @@ keywords = [ classifiers=[ "Development Status :: 4 - Beta", "Intended Audience :: Developers", - "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.10", @@ -53,7 +53,7 @@ towncrier = [ "towncrier==25.8.0", ] -tox-uv = [ +tox = [ "tox-uv == 1.36.0", ] @@ -61,15 +61,13 @@ dev = [ "setuptools_scm == 10.2.1", {include-group = "pre-commit"}, {include-group = "test"}, - {include-group = "tox-uv"}, + {include-group = "tox"}, ] +# Docs are always built on a specific Python version; see RTD and tox config files. +# beeware-docs-tools is not published to PyPI; install from the base repo. docs = [ - "pyenchant == 3.3.0", - "sphinx == 9.1.0", - "sphinx-autobuild == 2025.8.25", - "sphinx-rtd-theme == 3.1.0", - "sphinxcontrib-spelling == 8.0.2", + "beeware-docs-tools @ git+https://github.com/beeware/beeware-docs-tools@main", ] [project.urls] @@ -119,6 +117,37 @@ ignore = [ "tests/web_platform/css_flexbox_1/*.py" = ["N999"] "utils/w3c.py" = ["EXE001", "SIM115"] +[tool.rumdl] +flavor = "mkdocs" +include = ["**/*.md"] +exclude = ["docs/en/SUMMARY.md", "CODE_OF_CONDUCT.md", "changes/template.md"] +respect-gitignore = true + +# Disable rules: +# MD014: Force commands in codeblocks to show output +disable = ["MD014"] + +[tool.rumdl.MD013] # Line length +line_length = 999999 # Force reflow to paragraph content to remove linebreaks +reflow = true +reflow_mode = "normalize" + +[tool.rumdl.MD026] # Remove punctuation at the end of headings +punctuation = ",;:" + +[tool.rumdl.MD033] # No inline HTML +allowed_elements = ["nospell",] # pyspelling inline disable tag + +[tool.rumdl.MD061] +terms = ["TODO"] + +[tool.rumdl.per-file-ignores] +# MD041: First line in file should be level 1 heading; title will be included in the target page +"docs/en/how-to/contribute/**/*.md" = ["MD041"] +"docs/en/how-to/contribute/*.md" = ["MD041"] +# MD041: Change note fragments are prose snippets, not standalone documents +"changes/*.md" = ["MD041"] + [tool.setuptools_scm] # To enable SCM versioning, we need an empty tool configuration for setuptools_scm @@ -126,11 +155,10 @@ ignore = [ directory = "changes" package = "colosseum" package_dir = "src" -filename = "docs/background/releases.rst" -title_format = "{version} ({project_date})" -issue_format = "`#{issue} `_" -template = "changes/template.rst" -underlines = ["-", "^", "\""] +filename = "docs/en/about/releases.md" +title_format = false +template = "changes/template.md" +start_string = "" type = [ { directory = "feature", name = "Features", showcontent = true }, { directory = "bugfix", name = "Bugfixes", showcontent = true }, diff --git a/src/colosseum/__init__.py b/src/colosseum/__init__.py index 7691c4692..08772ce9c 100644 --- a/src/colosseum/__init__.py +++ b/src/colosseum/__init__.py @@ -1,5 +1,7 @@ -from .declaration import CSS +from importlib.metadata import version -__all__ = [ - "CSS", -] +from colosseum.declaration import CSS + +__all__ = ["CSS", "__version__"] + +__version__ = version("colosseum") diff --git a/tox.ini b/tox.ini index 03a0c0bcf..955c359d6 100644 --- a/tox.ini +++ b/tox.ini @@ -1,20 +1,5 @@ -# Flake8 doesn't believe in pyproject.toml, so we put the configuration here. -[flake8] -exclude= - local/*,\ - docs/*,\ - build/*,\ - dist/*,\ - .tox/*, \ - venv* -max-complexity = 25 -max-line-length = 119 -ignore = - # line break occurred before a binary operator - W503, - [tox] -envlist = towncrier-check,pre-commit,py{39,310,311,312,313,314} +envlist = towncrier-check,pre-commit,docs{,-lint,-all},py{311,312,313,314,315} skip_missing_interpreters = true [testenv:pre-commit] @@ -23,7 +8,7 @@ wheel_build_env = .pkg dependency_groups: pre-commit commands = pre-commit run --all-files --show-diff-on-failure --color=always -[testenv:py{,39,310,311,312,313,314}] +[testenv:py{,311,312,313,314,315}] package = wheel wheel_build_env = .pkg depends = @@ -42,9 +27,22 @@ commands = [docs] docs_dir = {tox_root}{/}docs -build_dir = {[docs]docs_dir}{/}_build -[testenv:docs] +[testenv:docs{,-lint,-links,-all,-live,-serve}] +# Docs are always built on Python 3.13. See also the RTD config. +base_python = py313 +package = wheel +wheel_build_env = .pkg dependency_groups = docs +passenv = + READTHEDOCS_CANONICAL_URL +setenv = + DISABLE_MKDOCS_2_WARNING = true + NO_MKDOCS_2_WARNING = 1 commands = - python -m sphinx -W -b html . _build/html + !lint-!links-!all-!live-!serve : build_md_translations {posargs} --source-code=src en + all : build_md_translations {posargs} --source-code=src en + live : live_serve_en {posargs} src --port=8046 --source-code=src + lint : pyspelling + links : markdown-checker --dir {tox_root}{/}docs{/}en --func check_broken_urls + serve : python -m http.server -d _build/html 8046