python/a11y: Add new page, #14

open-contracting · Dec 12, 2023 · 8c099aa · 8c099aa
1 parent 5db38a8
commit 8c099aa
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 1 deletion.
diff --git a/docs/python/a11y.rst 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
@@ -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
@@ -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
@@ -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