From 8c099aa543eaf393e353c14614aacb832bf5f5ca Mon Sep 17 00:00:00 2001
From: James McKinney <26463+jpmckinney@users.noreply.github.com>
Date: Mon, 11 Dec 2023 22:01:38 -0500
Subject: [PATCH] python/a11y: Add new page, #14

---
 docs/python/a11y.rst   | 49 ++++++++++++++++++++++++++++++++++++++++++
 docs/python/ci.rst     |  7 +++++-
 docs/python/django.rst |  2 ++
 docs/python/index.rst  |  1 +
 4 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 docs/python/a11y.rst

diff --git a/docs/python/a11y.rst b/docs/python/a11y.rst
new file mode 100644
index 0000000..f4f9774
--- /dev/null
+++ b/docs/python/a11y.rst
@@ -0,0 +1,49 @@
+Accessibility (a11y)
+====================
+
+Public sites should check for accessibility issues, using `Pa11y <https://pa11y.org>`__.
+
+Automated tests
+---------------
+
+Create a ``pa11y.default.json`` file for the default `configuration <https://github.com/pa11y/pa11y#configuration>`__, for example:
+
+.. code-block:: json
+
+   {
+     "defaults": {}
+   }
+
+Create a ``pa11y.mobile.json`` file for the mobile configuration, for example:
+
+.. code-block:: json
+
+   {
+     "viewport": {
+       "width": 320,
+       "height": 480,
+       "deviceScaleFactor": 2,
+       "isMobile": true
+     }
+   }
+
+Test individual URLs with `pa11y <https://github.com/pa11y/pa11y>`__, for example:
+
+.. code-block:: bash
+
+   pa11y -c pa11y.default.json http://127.0.0.1:8000
+
+If the site has a :ref:`sitemap<django-sitemap>`, use `pa11y-ci <>`__, for example:
+
+.. code-block:: bash
+
+   pa11y-ci -c pa11y.default.json -s http://127.0.0.1:8000/sitemap.xml
+
+.. _a11y-ci:
+
+Continuous integration
+----------------------
+
+.. note::
+
+   This section is a stub. For now, see the Data Registry's `a11y.yml <https://github.com/open-contracting/data-registry/blob/main/.github/workflows/a11y.yml>`__ workflow file.
diff --git a/docs/python/ci.rst b/docs/python/ci.rst
index f26a7a7..1503726 100644
--- a/docs/python/ci.rst
+++ b/docs/python/ci.rst
@@ -3,7 +3,12 @@ Continuous integration
 
 .. seealso::
 
-   Workflows for linting :doc:`Python<linting>`, :ref:`JavaScript<javascript-ci>` and :ref:`shell scripts<shell-ci>`, for :ref:`releasing packages<python-package-release-process>` and for :ref:`checking translations<i18n-ci>`
+   Workflows for:
+
+   -  Linting :doc:`Python<linting>`, :ref:`JavaScript<javascript-ci>` and :ref:`shell scripts<shell-ci>`
+   - :ref:`Releasing packages<python-package-release-process>`
+   - :ref:`Checking translations<i18n-ci>`
+   - :ref:`Checking accessibility<a11y-ci>`
 
 .. tip::
 
diff --git a/docs/python/django.rst b/docs/python/django.rst
index 473e303..0d2596e 100644
--- a/docs/python/django.rst
+++ b/docs/python/django.rst
@@ -51,6 +51,8 @@ URLs
 -  Use hyphens as separators in `named URL patterns <https://docs.djangoproject.com/en/4.2/topics/http/urls/#naming-url-patterns>`__.
 -  Use `Django REST Framework <https://www.django-rest-framework.org>`__, instead of writing REST endpoints by hand. (See :doc:`preferences`.)
 
+.. _django-sitemap:
+
 Sitemap
 ~~~~~~~
 
diff --git a/docs/python/index.rst b/docs/python/index.rst
index acf1432..214695d 100644
--- a/docs/python/index.rst
+++ b/docs/python/index.rst
@@ -21,6 +21,7 @@ Applications are upgraded to, at minimum, the Python version in the `latest Ubun
    file_formats
    style_guide
    i18n
+   a11y
    packages
    performance