From c5eb5a0bb5224ab9b7c8b264aa5f7dbad95f114d Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 6 Jan 2022 16:29:59 -0800 Subject: [PATCH 01/11] DOCS: refactor dev docs --- .github/workflows/tests.yml | 2 +- docs/_templates/custom-template.html | 6 - docs/_templates/navbar-version.html | 3 +- docs/changelog.rst | 9 - docs/conf.py | 22 +- docs/contribute/index.md | 58 ++++ docs/contribute/manual.md | 75 +++++ docs/contribute/setup.md | 150 +++++++++ docs/contribute/topics.md | 192 ++++++++++++ docs/contributing.rst | 452 --------------------------- docs/index.rst | 3 +- docs/{ => scripts}/a11y-roadmap.txt | 0 docs/{ => scripts}/a11y.py | 0 noxfile.py | 39 ++- pyproject.toml | 3 +- 15 files changed, 528 insertions(+), 486 deletions(-) delete mode 100644 docs/_templates/custom-template.html delete mode 100644 docs/changelog.rst create mode 100644 docs/contribute/index.md create mode 100644 docs/contribute/manual.md create mode 100644 docs/contribute/setup.md create mode 100644 docs/contribute/topics.md delete mode 100644 docs/contributing.rst rename docs/{ => scripts}/a11y-roadmap.txt (100%) rename docs/{ => scripts}/a11y.py (100%) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 0c0d05388..cbf32afd8 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -135,7 +135,7 @@ jobs: verbose: true - name: Run the accessibility audit - run: python docs/a11y.py --no-serve + run: python docs/scripts/a11y.py --no-serve # Check the audit for threshold values # TODO: write this someplace after a PR is merged, and load? diff --git a/docs/_templates/custom-template.html b/docs/_templates/custom-template.html deleted file mode 100644 index be9854c83..000000000 --- a/docs/_templates/custom-template.html +++ /dev/null @@ -1,6 +0,0 @@ -
- This is a community-supported theme. - If you'd like to contribute, - check out our GitHub repository - Your contributions are welcome! -
diff --git a/docs/_templates/navbar-version.html b/docs/_templates/navbar-version.html index 35aaf29b3..b23c1ca17 100644 --- a/docs/_templates/navbar-version.html +++ b/docs/_templates/navbar-version.html @@ -1 +1,2 @@ -v{{ version }} + +TEST: v{{ version }} diff --git a/docs/changelog.rst b/docs/changelog.rst deleted file mode 100644 index 369e044d2..000000000 --- a/docs/changelog.rst +++ /dev/null @@ -1,9 +0,0 @@ -********* -Changelog -********* - -See the `GitHub Releases `_ for the changelog of each release. - -.. meta:: - :description lang=en: - The historical releases for pydata-sphinx-theme. diff --git a/docs/conf.py b/docs/conf.py index cdbcf7aaa..8ca095410 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,11 +34,12 @@ # ones. extensions = [ + "jupyter_sphinx", + "myst_parser", + "numpydoc", "sphinx.ext.autodoc", "sphinx.ext.autosummary", - "numpydoc", - "myst_parser", - "jupyter_sphinx", + "sphinxext.rediraffe", ] # -- Internationalization ------------------------------------------------ @@ -64,11 +65,6 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -html_sidebars = { - "contributing": ["search-field", "custom-template"], - "changelog": [], -} - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -79,7 +75,11 @@ html_theme_options = { "external_links": [ - {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"} + { + "url": "https://github.com/pydata/pydata-sphinx-theme/releases", + "name": "Changelog", + }, + {"url": "https://pandas.pydata.org/pandas-docs/stable/", "name": "Pandas Docs"}, ], "github_url": "https://github.com/pydata/pydata-sphinx-theme", "twitter_url": "https://twitter.com/pandas_dev", @@ -115,6 +115,10 @@ "doc_path": "docs", } +rediraffe_redirects = { + "contributing.rst": "contribute/index.rst", +} + # 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". diff --git a/docs/contribute/index.md b/docs/contribute/index.md new file mode 100644 index 000000000..49f2f93ab --- /dev/null +++ b/docs/contribute/index.md @@ -0,0 +1,58 @@ +--- +html_meta: + "description lang=en": "How to become a contributor to the pydata-sphinx-theme." +--- + +# Contribute + +These pages contain information about how you can get up-and-running with a development version of this theme, and how you can contribute to the project. + +## Workflow for contributing changes + +We follow a [typical GitHub workflow](https://guides.github.com/introduction/flow/) +of: + +- create a personal fork of this repo +- create a branch +- open a pull request +- fix findings of various linters and checks +- work through code review + +For each pull request, the demo site is built and deployed to make it easier to review +the changes in the PR. To access this, click on the "ReadTheDocs" preview in the CI/CD jobs. + +## Location and structure of documentation + +The documentation for this theme is in the `docs/` folder. +It is structured as a [Sphinx documentation site](https://sphinx-doc.org). +The content is written in a combination of reStructuredText and MyST Markdown. + +## Location and structure of CSS/JS assets + +The CSS and JS for this theme are built for the browser from `src/*` with +[webpack](https://webpack.js.org/). The main entrypoints are: + +- CSS: `src/scss/index.scss` + + - the main part of the theme assets + - customizes [Bootstrap](https://getbootstrap.com/) with [Sass](https://sass-lang.com) + - points to the `font-face` of vendored web fonts, but does not include their + CSS `@font-face` declaration + +- JS: `src/js/index.js` + + - provides add-on Bootstrap features, as well as some custom navigation behavior + +- webpack: `webpack.config.js` + + - captures the techniques for transforming the JS and CSS source files in + `src/` into the production assets in `pydata_sphinx_theme/static/` + +**For more information** about developing this theme, see the sections below and in the left sidebar. + +```{toctree} +:maxdepth: 2 +setup +topics +manual +``` diff --git a/docs/contribute/manual.md b/docs/contribute/manual.md new file mode 100644 index 000000000..1361e46ba --- /dev/null +++ b/docs/contribute/manual.md @@ -0,0 +1,75 @@ +(manual-environment)= + +# Set up a manual development environment + +If you prefer not to use automation tools like `nox`, you may also manually set up a development environment locally. +To do so, follow the instructions on this page. + +## Create a new development environment + +This is optional, but it's best to start with a fresh development environment so that you've isolated the packages that you're using for this repository. + +To do so, use a tool like [conda](https://docs.conda.io/en/latest/), [mamba](https://github.com/mamba-org/mamba), or [virtualenv](https://virtualenv.pypa.io/). + +## Clone the repository locally + +First clone this repository from the `pydata` organization, or from a fork that you have created: + +```console +$ git clone https://github.com/pydata/pydata-sphinx-theme +$ cd pydata-sphinx-theme +``` + +## Install the `sphinx-theme-builder` + +We use the `sphinx-theme-builder` to install `nodejs` locally and to compile all CSS and JS assets needed for the theme. +Install it like so (note the `cli` option so that we can run it from the command line): + +```console +$ pip install sphinx-theme-builder[cli] +``` + +## Install this theme locally + +Next, install this theme locally so that we have the necessary dependencies to build the documentation and testing suite: + +```console +$ pip install -e .[dev] +``` + +Note that the `sphinx-theme-builder` will automatically install a local copy of `nodejs` for building the theme's assets. +This will be placed in a `.nodeenv` folder. + +## Build the documentation + +To manually build the documentation, run the following command: + +```console +$ sphinx-build docs docs/_build/html +``` + +## Compile web assets (JS/CSS) + +To compile the javascript and CSS assets for the theme, run the following command: + +```console +$ stb compile +``` + +This will compile everything in the `src/pydata_sphinx_theme/assets` folder and place them in the appropriate places in our theme's folder structure. + +## Start a live-server to build and serve your documentation + +To manually open a server to watch your documentation for changes, build them, and display them locally in a browser, run this command: + +```console +$ stb serve docs --open-browser +``` + +## Run the tests + +To manually run the tests for this theme, first set up your environment locally, and then run: + +```console +$ pytest +``` diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md new file mode 100644 index 000000000..da98e87e3 --- /dev/null +++ b/docs/contribute/setup.md @@ -0,0 +1,150 @@ +# Get started with development + +This section covers the simplest way to get started developing this theme locally so that you can contribute. +It uses automation and as few steps as possible to get things done. +If you'd like to do more operations manually, see [](manual.md). + +## Clone the repository + +First off you'll need your own copy of the `pydata-sphinx-theme` codebase. +You can clone it for local development like so: + +1. **Fork the repository** so you have your own copy on GitHub. + See [the GitHub forking guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for more information. +2. **Clone the repository locally** so that you have a local copy to work from: + + ```console + $ git clone https://github.com/{{ YOUR USERNAME }}/pydata-sphinx-theme + $ cd pydata-sphinx-theme + ``` + +## Install your tools + +Building a Sphinx site uses a combination of Python and Jinja to manage HTML, SCSS, and Javascript. +To simplify this process, we use a few helper tools: + +- [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) to automatically perform compilation of web assets. +- [pre-commit](https://pre-commit.com/) for automatically enforcing code standards and quality checks before commits. +- [nox](https://nox.thea.codes/), for automating common development tasks. + +In particular, `nox` can be used to automatically create isolated local development environments with all of the correct packages installed to work on the theme. +The rest of this guide focuses on using `nox` to start with a basic environment. + +```{seealso} +The information on this page covers the basics to get you started, for information about manually compiling assets, see [](manual.md). +``` + +### Setup `nox` + +To start, install `nox`: + +```console +$ pip install nox +``` + +You can call `nox` from the command line in order to perform common actions that are needed in building the theme. +`nox` operates with isolated environments, so each action has its own packages installed in a local director (`.nox`). +For common development actions, you'll simply need to use `nox` and won't need to set up any other packages. + +### Setup `pre-commit` + +`pre-commit` allows us to run several checks on the codebase every time a new Git commit is made. +This ensures standards and basic quality control for our code. + +Install `pre-commit` with the following command: + +```console +$ pip install pre-commit +``` + +then navigate to this repository's folder and activate it like so: + +```console +$ pre-commit install +``` + +This will install the necessary dependencies to run `pre-commit` every time you make a commit with Git. + +## Build the documentation + +Now that you have `nox` installed and cloned the repository, you should be able to build the documentation locally. + +To build the documentation with `nox`, run the following command: + +```console +$ nox -s docs +``` + +This will install the necessary dependencies and build the documentation located in the `docs/` folder. +They will be placed in a `docs/_build/html` folder. +If the docs have already been built, it will only build new pages that have been updated. +You can open one of the HTML files there to preview the documentation locally. + +### Change content and re-build + +Now that you've built the documentation, edit one of the source files to see how the documentation updates with new builds. + +1. **Make an edit to a page**. For example, add a word or fix a typo on any page. +2. **Rebuild the documentation** with `nox -s docs` + +It should go much faster this time, because `nox` is re-using the old environment, and because Sphinx has cached the pages that you didn't change. + +## Compile the CSS/JS assets + +The source files for CSS and JS assets are in `src/pydata_sphinx_theme/assets`. +These are then built and bundled with the theme (e.g., `scss` is turned into `css`). + +To compile the CSS/JS assets with `nox`, run the following command: + +```console +$ nox -s compile +``` + +This will compile all assets and place them in the appropriate folder to be used with documentation builds. + +```{note} +Compiled assets are **not committed to git**. +The `sphinx-theme-builder` will bundle these assets automatically when we make a new release, but we do not manually commit these compiled assets to git history. +``` + +## Run a development server + +You can combine the above two actions and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window. + +To run the development server with `nox`, run the following command: + +```console +$ nox -s docs-live +``` + +When working on the theme, saving changes to any of these directories: + +- `src/js/index.js` +- `src/scss/index.scss` +- `docs/**/*.rst` +- `docs/**/*.py` + +will cause the development server to do the following: + +- bundle/copy the CSS, JS, and vendored fonts +- regenerate the Jinja2 macros +- re-run Sphinx + +## Run the tests + +This theme uses `pytest` for its testing, with a lightweight fixture defined +in the `test_build.py` script that makes it easy to run a Sphinx build using +this theme and inspect the results. + +In addition, we use [pytest-regressions](https://pytest-regressions.readthedocs.io/en/latest/) +to ensure that the HTML generated by the theme is what we'd expect. This module +provides a `file_regression` fixture that will check the contents of an object +against a reference file on disk. If the structure of the two differs, then the +test will fail. If we _expect_ the structure to differ, then delete the file on +disk and run the test. A new file will be created, and subsequent tests will pass. + +To run the tests with `nox`, run the following command: + +```console +$ nox -s test +``` diff --git a/docs/contribute/topics.md b/docs/contribute/topics.md new file mode 100644 index 000000000..c60beee17 --- /dev/null +++ b/docs/contribute/topics.md @@ -0,0 +1,192 @@ +# Topic guides and how-tos + +These sections cover common operations and topics that are relevant to developing this theme. + +## Make a release + +This theme uses GitHub tags and releases to automatically push new releases to +PyPI. For information on this process, see [the release checklist](https://github.com/pydata/pydata-sphinx-theme/wiki/Release-checklist#release-instructions). + +## Update JavaScript dependencies and their versions + +The javascript dependencies for this package are defined in `package.json`, and broken down into a few categories like `dependencies` and `devDependencies`. + +To update or add JS dependency, modify (or append to) the list of packages that are listed in each of these sections. +The next time you build the documentation (either with `nox` or with `stb`), these new dependencies will be installed and bundled with the theme. + +## Using `nox` + +Here are a few extra tips for using `nox`. + +### Re-install dependencies + +To re-execute the installation commands, use this pattern: + +```console +$ nox -s docs -- reinstall +``` + +Or to completely remove the environment generated by `nox` and start from scratch: + +```console +$ rm -rf .nox/docs +``` + +### Use `nox` with your global environment + +If you'd like to use `nox` with your **global** environment (the one from which you are calling `nox`), you can do so with: + +```console +$ nox --force-venv-backend none + +# alternatively: +$ nox -fb none +``` + +Using `none` will re-use your current global environment. +See +[the nox documentation](https://nox.thea.codes/en/stable/usage.html#forcing-the-sessions-backend) for more details. + +## Using `pre-commit` + +Here are a few tips for using `pre-commit`: + +### Skip the pre-commit checks + +Run the following command: + +```console +$ git commit --no-verify +``` + +### Run pre-commit on all files + +By default, `pre-commit` will run its checks on files that have been modified in a commit. +To instead run it on all files, use this command: + +```console +$ pre-commit run --all-files + +# Alternatively +$ pre-commit run -a +``` + +## Web asset compiling and bundling + +All of the CSS and JS assets stored in `src/pydata_sphinx_theme/assets` will be compiled and bundled with the theme when you build it locally. +These bundled assets will be placed in `src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static`. + +The configuration that defines what happens upon compilation is at `webpack.config.js`. + +When assets are compiled, a `` is generated for each, and appended to the end of the asset's reference in the HTML templates of the theme. +This ensures the correct asset versions are served when viewers return to your +site after upgrading the theme. + +Web fonts, and their supporting CSS, are copied into +`src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static/vendor///`. + +The links to these unique file names are captured as Jinja2 macros that are defined in HTML templates bundled with the theme. + +## Accessibility checks + +The accessibility checking tools can find a number of common HTML patterns which +assistive technology can't help users understand. + +In addition to [Lighthouse](https://developers.google.com/web/tools/lighthouse) +in CI, the `pa11y` stack is installed as part of the development environment. + +The key components are: + +- [pa11y](https://github.com/pa11y/pa11y) which uses a headless browser to analyze + an HTML page with a configurable set of rules based on publish standards +- [Pa11y-CI](https://github.com/pa11y/pa11y-ci) runs `pa11y` on multiple pages +- [pa11y-reporter-html](https://github.com/pa11y/pa11y-reporter-html) generates + some nice HTML reports, suitable for review + +:::{note} +Presently, the _default_ `pa11y` ruleset, `WCAG2AA` is used, a subset of +the [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21). +The [Quick Reference](https://www.w3.org/WAI/WCAG21/quickref) may provide +lighter reading. +::: + +### Run an accessibility audit locally + +To run the accessibility problem finder locally: + +```console +$ nox -s compile # Compile the theme assets +$ nox -s docs # Build the documentation +$ python docs/scripts/a11y.py # Run a helper script for an accessibility audit +``` + +The output of the last command includes: + +- a short summary of the current state of the accessibility rules we are trying to maintain +- local paths to JSON and HTML reports which contain all of the issues found + +### Fix accessibility errors + +Start by checking for issues on the +[accessibility roadmap](https://github.com/pandas-dev/pydata-sphinx-theme/blob/master/docs/a11y-roadmap.txt). +These are issues which are currently flagged by the toolset, but that have not yet +been fixed. If that file is empty (or just comments), hooray! + +To start working on one of the accessibility roadmap items, comment out one of the +lines in `docs/a11y-roadmap.txt`, and re-run the audit to establish a baseline. + +Then, fix the issue in either the HTML templates, CSS, or python code, and re-run +the audit until it is fixed. + +## Change fonts + +Three "styles" of the [FontAwesome 5 Free](https://fontawesome.com/icons?m=free) +icon font are used for {ref}`icon links ` and admonitions, and is +the only `vendored` font. Further font choices are described in the {ref}`customizing` +section of the user guide, and require some knowledge of HTML and CSS. + +The remaining vendored font selection is: + +- managed as a dependency in `package.json` + + - allowing the version to be managed centrally + +- copied directly into the site statics, including licenses + + - allowing the chosen font to be replaced (or removed entirely) with minimal + templating changes: practically, changing the icon font is difficult at this + point. + +- partially preloaded + + - reducing flicker and re-layout artifacts of early icon renders + +- mostly managed in `webpack.js` + + - allowing upgrades to be handled in a relatively sane, manageable way, to + ensure the most recent icons + +### Upgrade a font + +If _only_ the version of the `existing` font must change, for example to enable +new icons, edit the appropriate font version in `package.json`. +Then re-compile the theme with: + +```console +$ nox -s compile +``` + +### Change a font + +If the above doesn't work, for example if file names for an existing font change, +or a new font variant altogether is being added, hand-editing of `webpack.config.js` +is required. The steps are roughly: + +- install the new font, as above +- in `webpack.config.js`: + - add the new font to `vendorVersions` and `vendorPaths` + - add new `link` tags to the appropriate macro in `macroTemplate` + - add the new font files (including the license) to `CopyPlugin` + - remove references to the font being replaced/removed, if applicable + - see the `font-awesome` sections of this configuration to see what the end-result configuration looks like. +- re-compile the theme's assets: `nox -s compile` diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index 6d6fc992c..000000000 --- a/docs/contributing.rst +++ /dev/null @@ -1,452 +0,0 @@ -************ -Contributing -************ - -The documentation for this theme (what you are looking at now) also serves -as a demo site for the theme. -These sections describe how to get set up with a development environment, and begin contributing. - -.. _basic-environment: - -Set up a basic development environment -====================================== - -We automate many development tasks with these two tools: - -- `nox `_, for automating common development tasks -- `pre-commit `_ for automatically enforcing code standards - -At a minimum, set up your local environment with these two tools by running the following command: - -.. code-block:: console - - $ pip install .[dev] - -Then, activate ``pre-commit`` locally with the following command: - -.. code-block:: console - - $ pre-commit install - -Most sections below use ``nox`` to automate tasks and environments. -This allows you to run jobs in a contained environment so that you know what tools are installed. -There's also a section below that describes how to manually set up your environment. - - -Build the documentation -======================= - -Building the documentation will use ``sphinx`` to generate the latest documentation in ``docs/`` and place them in a ``docs/_build/html`` folder. -If the docs have already been built, it will only build new pages that have been updated. - -To build the documentation with ``nox``, first follow :ref:`basic-environment`, -then run the following command: - -.. code-block:: console - - $ nox -s docs - -This will re-use pre-existing environments if possible. To re-execute the installation commands, use this pattern: - -.. code-block:: console - - $ nox -s docs -- reinstall - -Or to completely remove the environment generated by ``nox`` and start from scratch: - -.. code-block:: console - - $ rm -rf .nox/docs - -.. admonition:: Use nox with your global environment - :class: tip - - If you'd like to use ``nox`` with your **global** environment (the one from - which you are calling ``nox``), you can do so with - - .. code-block:: console - - $ nox --force-venv-backend none - - # alternatively: - $ nox -fb none - - Using `none` will re-use your current global environment. See - `the nox documentation `_ - for more details. - -If you've :ref:`manually set up your environment `, you can build them with: - -.. code-block:: console - - $ cd docs - $ make html - -.. Note:: - - If you wish to customize the CSS or JS beyond what is available in the - :ref:`configuration` and :ref:`customizing` sections of the user guide, - extra steps are required. The next section covers the full workflow, from - changing the source files, to seeing the updated site. - -Build the CSS/JS assets -======================= - -The source files for CSS and JS assets are in ``src/``. -These are then built and bundled with the theme (e.g., ``scss`` is turned into ``css``). -Building the CSS/JS assets requires a javascript development stack (``yarn``, ``webpack``, and anything in ``yarn.lock``). - -To build the CSS/JS assets with ``nox``, first follow :ref:`basic-environment`, -then run the following command: - -.. code-block:: console - - $ nox -s build - -If you've :ref:`manually set up your environment `, you can build them with: - -.. code-block:: console - - $ yarn build:production - - -Run a development server -======================== - -You can run a development server so that changes to make to ``src/`` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window. - -When working on the theme, saving changes to any of these directories: - -- ``src/js/index.js`` -- ``src/scss/index.scss`` -- ``docs/**/*.rst`` -- ``docs/**/*.py`` - -will cause the development server to do the followin: - -- bundle/copy the CSS, JS, and vendored fonts -- regenerate the Jinja2 macros -- re-run Sphinx - -To run the development server with ``nox``, first follow :ref:`basic-environment`, -then run the following command: - -.. code-block:: console - - $ nox -s docs-live - - -Run the tests -============= - -This theme uses ``pytest`` for its testing, with a lightweight fixture defined -in the ``test_build.py`` script that makes it easy to run a Sphinx build using -this theme and inspect the results. - -In addition, we use `pytest-regressions `_ -to ensure that the HTML generated by the theme is what we'd expect. This module -provides a ``file_regression`` fixture that will check the contents of an object -against a reference file on disk. If the structure of the two differs, then the -test will fail. If we *expect* the structure to differ, then delete the file on -disk and run the test. A new file will be created, and subsequent tests will pass. - -To run the tests with ``nox``, first follow :ref:`basic-environment`, -then run the following command: - -.. code-block:: console - - $ nox -s test - -If you've :ref:`manually set up your environment `, you can build them with: - -.. code-block:: console - - $ pytest - -.. _manual-environment: - -Manually set up a development environment -========================================= - -To set up your development environment, you'll need to set up both a Python and a Javascript environment. -As a convenience, this environment is described in the file at ``environment.yml``. -However, the sections below cover how to install it manually. - -Install python development dependencies ---------------------------------------- - -To install this theme locally, along with the dependencies needed to develop it, take the following steps: - -1. **Clone the repository locally**. Run this command: - - .. code-block:: console - - $ git clone https://github.com/pydata/pydata-sphinx-theme - $ cd pydata-sphinx-theme - -2. **Install the theme with dev dependencies**. Run this command: - - .. code-block:: console - - $ pip install -e .[dev] - -Install javascript development dependencies -------------------------------------------- - -The javascript development workflow relies primarily on `the yarn package managed `__. -This will be used to install a number of javascript dependencies defined originally in ``package.json``, and with specific versions pinned in ``yarn.lock``. -The easiest way to accomplish this is using `conda-forge `_, which these instructions cover below. - -1. **Install yarn**: - - .. code-block:: console - - $ conda install -c conda-forge yarn "nodejs>=14,<15" - - Re recommend using node 14 as it is the latest LTS release of ``nodejs``. - -2. **Initialize your yarn environment**: - - .. code-block:: console - - $ yarn --frozen-lockfile - - This will install all of the dependencies defined in ``yarn.lock`` and place them in a folder at ``node_modules/``. - - .. note:: - - If you do not include ``--frozen-lockfile``, then yarn will update all of the frozen dependency versions in ``yarn.lock``. - If you accidentally do this, revert the changes to ``yarn.lock`` and re-run the command with ``--frozen-lockfile``. - - -Update JS dependencies and their versions -========================================= - -The javascript dependencies for this package are defined in ``package.json``, and broken down into a few categories like ``dependencies`` and ``devDependencies``. -While ``package.json`` defines files versions loosely, explicit versions are "frozen" into a file called ``yarn.lock``. - -If you wish to update the versions of this theme's JS dependencies, follow these steps: - -1. Update packages in ``packages.json``. -2. Run the ``yarn`` command **without** ``--frozen-lockfile``. - - .. code-block:: console - - $ yarn - -3. Commit changes to ``yarn.lock`` and ``package.json``. It's important that both of these are changed together to ensure our builds are reproducible. - - -Location and structure of CSS/JS assets -======================================= - -The CSS and JS for this theme are built for the browser from ``src/*`` with -`webpack `__. The main entrypoints are: - -- CSS: ``src/scss/index.scss`` - - - the main part of the theme assets - - customizes `Bootstrap `__ with `Sass `__ - - points to the ``font-face`` of vendored web fonts, but does not include their - CSS ``@font-face`` declaration - -- JS: ``src/js/index.js`` - - - provides add-on Bootstrap features, as well as some custom navigation behavior - -- webpack: ``webpack.js`` - - - captures the techniques for transforming the JS and CSS source files in - ``src/`` into the production assets in ``pydata_sphinx_theme/static/`` - -These entrypoints, and all files they reference, are bundled into -``pydata_sphinx_theme/static/{css,js}/index..{css,js}``. - -The ```` ensures the correct asset versions are served when viewers return to your -site after upgrading the theme, and is reproducibly derived from ``src/**/*``, -``webpack.js``, and the ``dependencies`` and ``devDependencies`` -in ``package.json``/``yarn.lock``. - -Web fonts, and their supporting CSS, are copied into -``pydata_sphinx_theme/static/vendor///``. Including -the ```` also ensures the correct assets are served when upgrading. - -The links to these unique file names are captured as Jinja2 macros in -``pydata_sphinx_theme/static/webpack-macros.html``. - -Finally, all of these files are committed to the repo, in-place, along with the -rest of the code. This allows use of the theme directly from a ``git`` checkout, -without any of the finicky web development dependencies, or even a ``nodejs`` -runtime. - -.. Hint:: - - Theme development was inspired by the - `ReadTheDocs Sphinx theme `__. - -Change fonts -============ - -Three "styles" of the `FontAwesome 5 Free `__ -icon font are used for :ref:`icon links ` and admonitions, and is -the only `vendored` font. Further font choices are described in the :ref:`customizing` -section of the user guide, and require some knowledge of HTML and CSS. - -The remaining vendored font selection is: - -- managed as a dependency in ``package.json`` - - - allowing the version to be managed centrally - -- copied directly into the site statics, including licenses - - - allowing the chosen font to be replaced (or removed entirely) with minimal - templating changes: practically, changing the icon font is difficult at this - point. - -- partially preloaded - - - reducing flicker and re-layout artifacts of early icon renders - -- mostly managed in ``webpack.js`` - - - allowing upgrades to be handled in a relatively sane, manageable way, to - ensure the most recent icons - - -Upgrade a font --------------- - -If *only* the version of the `existing` font must change, for example to enable -new icons, run: - -.. code-block:: bash - - yarn add @ - yarn build:production - -It *may* also be necessary to clear out old font versions from -``pydata_sphinx_theme/static/vendor/`` before committing. - - -Change a font -------------- - -If the above doesn't work, for example if file names for an existing font change, -or a new font variant altogether is being added, hand-editing of ``webpack.js`` -is required. The steps are roughly: - -- install the new font, as above, with ``yarn add`` -- in ``webpack.js``: - - - add the new font to ``vendorVersions`` and ``vendorPaths`` - - add new ``link`` tags to the appropriate macro in ``macroTemplate`` - - add the new font files (including the license) to ``CopyPlugin`` - - remove references to the font being replaced/removed, if applicable - -- restart the development server, if running -- rebuild the production assets, as above, with ``yarn build:production`` -- potentially remove the font being replaced from ``package.json`` and re-run ``yarn`` -- commit all of the changed files - - -Workflow for contributing changes -================================= - -We follow a `typical GitHub workflow `__ -of: - -- create a personal fork of this repo -- create a branch -- open a pull request -- fix findings of various linters and checks -- work through code review - -For each pull request, the demo site is built and deployed to make it easier to review -the changes in the PR. To access this, click on the "ReadTheDocs" preview in the CI/CD jobs. - - -Automate code standards with pre-commit -======================================= - -To ensure all source files have been correctly built, a `pre-commit `__ hook is available. - -Pre-commit should be installed automatically by following the instructions in :ref:`basic-environment`. - -After running ``pre-commit install``, the pre-commit checks will be run every time you make a commit to the repository. - -- **To skip the pre-commit checks**, run the following command: - - .. code-block:: bash - - git commit --no-verify - -- **To run pre-commit on all files**, run the following command: - - .. code-block:: bash - - pre-commit run --all-files - -Accessibility checks -==================== - -The accessibility checking tools can find a number of common HTML patterns which -assistive technology can't help users understand. - -In addition to `Lighthouse `__ -in CI, the ``pa11y`` stack is installed as part of the development environment. - -The key components are: - -- `pa11y `__ which uses a headless browser to analyze - an HTML page with a configurable set of rules based on publish standards -- `Pa11y-CI `__ runs ``pa11y`` on multiple pages -- `pa11y-reporter-html `__ generates - some nice HTML reports, suitable for review - -.. Note:: - - Presently, the *default* ``pa11y`` ruleset, ``WCAG2AA`` is used, a subset of - the `Web Content Accessibility Guidelines `__. - The `Quick Reference `__ may provide - lighter reading. - -To run the accessibility problem finder locally: - -.. code-block:: bash - - yarn build:production - cd docs - make html - python a11y.py - -The output of the last command includes: - -- a short summary of the current state of the accessibility rules we are trying to maintain -- local paths to JSON and HTML reports which contain all of the issues found - - -Fixing accessibility errors ---------------------------- - -Start by checking for issues on the -`accessibility roadmap `__. -These are issues which are currently flagged by the toolset, but that have not yet -been fixed. If that file is empty (or just comments), hooray! - -To start working on one of the accessibility roadmap items, comment out one of the -lines in `docs/a11y-roadmap.txt`, and re-run the audit to establish a baseline. - -Then, fix the issue in either the HTML templates, CSS, or python code, and re-run -the audit until it is fixed. - - -Make a release -============== - -This theme uses GitHub tags and releases to automatically push new releases to -PyPI. For information on this process, see `the release checklist `_. - -.. meta:: - :description lang=en: - How to become a contributor to the pydata-sphinx-theme. diff --git a/docs/index.rst b/docs/index.rst index 16fe0b6c1..fd4862fc9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,14 +23,13 @@ Other sites that are using this theme: :maxdepth: 2 user_guide/index - contributing + contribute/index .. toctree:: :maxdepth: 2 :hidden: demo/index - changelog .. meta:: diff --git a/docs/a11y-roadmap.txt b/docs/scripts/a11y-roadmap.txt similarity index 100% rename from docs/a11y-roadmap.txt rename to docs/scripts/a11y-roadmap.txt diff --git a/docs/a11y.py b/docs/scripts/a11y.py similarity index 100% rename from docs/a11y.py rename to docs/scripts/a11y.py diff --git a/noxfile.py b/noxfile.py index 0b6beed86..38bd8f2ce 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,22 +1,53 @@ import nox +from pathlib import Path nox.options.reuse_existing_virtualenvs = True +def _should_install(session): + """Decide if we should install an environment or if it already exists. + + This speeds up the local install considerably because building the wheel + for this package takes some time. + + We assume that if `sphinx-build` is in the bin/ path, the environment is + installed. + """ + bin_files = list(Path(session.bin).glob("*")) + sphinx_is_installed = any("sphinx-build" in ii.name for ii in bin_files) + force_reinstall = "reinstall" in session.posargs + should_install = not sphinx_is_installed or force_reinstall + if should_install: + session.log("Installing fresh environment...") + else: + session.log("Skipping environment install...") + + +@nox.session +def compile(session): + if _should_install(session): + session.install(".") + session.install("sphinx-theme-builder[cli]") + session.run("stb", "compile") + + @nox.session def docs(session): - session.install(".[doc]") + if _should_install(session): + session.install(".[doc]") session.run("sphinx-build", "-b=html", "docs/", "docs/_build/html") @nox.session(name="docs-live") def docs_live(session): - session.install(".[doc]") - session.install("sphinx-theme-builder[cli]") + if _should_install(session): + session.install(".[doc]") + session.install("sphinx-theme-builder[cli]") session.run("stb", "serve", "docs", "--open-browser") @nox.session(name="test") def test(session): - session.install("-e", ".[test]") + if _should_install(session): + session.install("-e", ".[test]") session.run("pytest", *session.posargs) diff --git a/pyproject.toml b/pyproject.toml index 1c3ab0416..fce0c0c3f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,13 +39,12 @@ classifiers = [ [project.optional-dependencies] doc = [ - "sphinx", "numpydoc", "myst-parser", "pandas", "pytest", "pytest-regressions", - "beautifulsoup4", + "sphinxext-rediraffe", "sphinx-sitemap", # For demo examples "jupyter_sphinx", From 2fe7afecc0d34d4e4b6bfc507c76c6e49d2341db Mon Sep 17 00:00:00 2001 From: Damian Avila Date: Mon, 10 Jan 2022 15:10:10 -0300 Subject: [PATCH 02/11] Add http.server reference to quickly serve the built site --- docs/contribute/setup.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md index da98e87e3..c935ab806 100644 --- a/docs/contribute/setup.md +++ b/docs/contribute/setup.md @@ -80,6 +80,14 @@ They will be placed in a `docs/_build/html` folder. If the docs have already been built, it will only build new pages that have been updated. You can open one of the HTML files there to preview the documentation locally. +Alternatively, you can invoke the built-in Python [http.server](https://docs.python.org/3/library/http.server.html#module-http.server) with: + +```console +python -m http.server +``` + +and navigate to the `index.html` page under `docs/_build/html` folder. + ### Change content and re-build Now that you've built the documentation, edit one of the source files to see how the documentation updates with new builds. From f0fefe945d43224ce7b863ad71072671c651ccaf Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 10 Jan 2022 10:16:14 -0800 Subject: [PATCH 03/11] Update docs/contribute/setup.md --- docs/contribute/setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md index c935ab806..956422b5c 100644 --- a/docs/contribute/setup.md +++ b/docs/contribute/setup.md @@ -83,10 +83,10 @@ You can open one of the HTML files there to preview the documentation locally. Alternatively, you can invoke the built-in Python [http.server](https://docs.python.org/3/library/http.server.html#module-http.server) with: ```console -python -m http.server +$ python -m http.server -d _build/html/ ``` -and navigate to the `index.html` page under `docs/_build/html` folder. +This will print a local URL that you can open in a browser to explore the HTML files. ### Change content and re-build From e763a2017963ccbe0eae3398177c98dd0b92cf84 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 10 Jan 2022 10:16:51 -0800 Subject: [PATCH 04/11] Update docs/contribute/topics.md Co-authored-by: Damian Avila --- docs/contribute/topics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/topics.md b/docs/contribute/topics.md index c60beee17..efae2bf18 100644 --- a/docs/contribute/topics.md +++ b/docs/contribute/topics.md @@ -128,7 +128,7 @@ The output of the last command includes: ### Fix accessibility errors Start by checking for issues on the -[accessibility roadmap](https://github.com/pandas-dev/pydata-sphinx-theme/blob/master/docs/a11y-roadmap.txt). +[accessibility roadmap](https://github.com/pydata/pydata-sphinx-theme/blob/master/docs/a11y-roadmap.txt). These are issues which are currently flagged by the toolset, but that have not yet been fixed. If that file is empty (or just comments), hooray! From 3a8a8cd25ce3aba07ce36dbfa5a84404c580f552 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 10 Jan 2022 10:18:22 -0800 Subject: [PATCH 05/11] Update noxfile.py --- noxfile.py | 1 + 1 file changed, 1 insertion(+) diff --git a/noxfile.py b/noxfile.py index 38bd8f2ce..2a3479558 100644 --- a/noxfile.py +++ b/noxfile.py @@ -21,6 +21,7 @@ def _should_install(session): session.log("Installing fresh environment...") else: session.log("Skipping environment install...") + return should_install @nox.session From d7dbe188e414f1b40e6e75b7186837c0d4cb7759 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 10 Jan 2022 13:16:31 -0800 Subject: [PATCH 06/11] Update docs/contribute/setup.md Co-authored-by: Joris Van den Bossche --- docs/contribute/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md index 956422b5c..df6ec39b7 100644 --- a/docs/contribute/setup.md +++ b/docs/contribute/setup.md @@ -43,7 +43,7 @@ $ pip install nox ``` You can call `nox` from the command line in order to perform common actions that are needed in building the theme. -`nox` operates with isolated environments, so each action has its own packages installed in a local director (`.nox`). +`nox` operates with isolated environments, so each action has its own packages installed in a local directory (`.nox`). For common development actions, you'll simply need to use `nox` and won't need to set up any other packages. ### Setup `pre-commit` From 2513ba37d8f836bf6b2a8d4f15635b7053df1264 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 10 Jan 2022 13:18:07 -0800 Subject: [PATCH 07/11] Update docs/contribute/setup.md Co-authored-by: Joris Van den Bossche --- docs/contribute/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md index df6ec39b7..2658923bf 100644 --- a/docs/contribute/setup.md +++ b/docs/contribute/setup.md @@ -83,7 +83,7 @@ You can open one of the HTML files there to preview the documentation locally. Alternatively, you can invoke the built-in Python [http.server](https://docs.python.org/3/library/http.server.html#module-http.server) with: ```console -$ python -m http.server -d _build/html/ +$ python -m http.server -d docs/_build/html/ ``` This will print a local URL that you can open in a browser to explore the HTML files. From de670a1fda558e20b89db3481d6a0e26bfa3afad Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 10 Jan 2022 13:26:31 -0800 Subject: [PATCH 08/11] Address review comments --- docs/conf.py | 7 +++++++ docs/contribute/index.md | 8 ++++---- docs/contribute/manual.md | 3 ++- docs/contribute/setup.md | 5 +++++ docs/contribute/topics.md | 6 +++++- noxfile.py | 3 +++ 6 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8ca095410..4d53863c5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -107,6 +107,13 @@ }, } +html_sidebars = { + "contributing": [ + "search-field", + "custom-template", + ], # This ensures we test for custom sidebars +} + html_context = { "github_user": "pandas-dev", diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 49f2f93ab..b397ec748 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -29,24 +29,24 @@ The content is written in a combination of reStructuredText and MyST Markdown. ## Location and structure of CSS/JS assets -The CSS and JS for this theme are built for the browser from `src/*` with +The CSS and JS for this theme are built for the browser from `src/pydata_sphinx_theme/assets/*` with [webpack](https://webpack.js.org/). The main entrypoints are: -- CSS: `src/scss/index.scss` +- CSS: `src/pydata_sphinx_theme/assets/styles/index.scss` - the main part of the theme assets - customizes [Bootstrap](https://getbootstrap.com/) with [Sass](https://sass-lang.com) - points to the `font-face` of vendored web fonts, but does not include their CSS `@font-face` declaration -- JS: `src/js/index.js` +- JS: `src/pydata_sphinx_theme/assets/scripts/index.js` - provides add-on Bootstrap features, as well as some custom navigation behavior - webpack: `webpack.config.js` - captures the techniques for transforming the JS and CSS source files in - `src/` into the production assets in `pydata_sphinx_theme/static/` + `src/pydata_sphinx_theme/assets/*` into the production assets in `src/theme/pydata_sphinx_theme/static/` **For more information** about developing this theme, see the sections below and in the left sidebar. diff --git a/docs/contribute/manual.md b/docs/contribute/manual.md index 1361e46ba..7da89c758 100644 --- a/docs/contribute/manual.md +++ b/docs/contribute/manual.md @@ -2,7 +2,8 @@ # Set up a manual development environment -If you prefer not to use automation tools like `nox`, you may also manually set up a development environment locally. +If you prefer not to use automation tools like `nox`, or want to have more control over the specific version of packages that you'd like like installed, you may also manually set up a development environment locally. + To do so, follow the instructions on this page. ## Create a new development environment diff --git a/docs/contribute/setup.md b/docs/contribute/setup.md index 956422b5c..f62fc3e70 100644 --- a/docs/contribute/setup.md +++ b/docs/contribute/setup.md @@ -65,6 +65,11 @@ $ pre-commit install This will install the necessary dependencies to run `pre-commit` every time you make a commit with Git. +:::{note} +Your `pre-commit` dependencies will be installed in the environment from which you're calling `pre-commit`, `nox`, etc. +They will not be installed in the isolated environments used by `nox`. +::: + ## Build the documentation Now that you have `nox` installed and cloned the repository, you should be able to build the documentation locally. diff --git a/docs/contribute/topics.md b/docs/contribute/topics.md index efae2bf18..a2a2a1cc3 100644 --- a/docs/contribute/topics.md +++ b/docs/contribute/topics.md @@ -18,6 +18,10 @@ The next time you build the documentation (either with `nox` or with `stb`), the Here are a few extra tips for using `nox`. +:::{seealso} +The [`nox` command line documentation](https://nox.thea.codes/en/stable/usage.html) has a lot of helpful tips for extra functionality you can enable with the CLI. +::: + ### Re-install dependencies To re-execute the installation commands, use this pattern: @@ -40,7 +44,7 @@ If you'd like to use `nox` with your **global** environment (the one from which $ nox --force-venv-backend none # alternatively: -$ nox -fb none +$ nox --no-venv ``` Using `none` will re-use your current global environment. diff --git a/noxfile.py b/noxfile.py index 2a3479558..0a1d9d6c7 100644 --- a/noxfile.py +++ b/noxfile.py @@ -13,6 +13,9 @@ def _should_install(session): We assume that if `sphinx-build` is in the bin/ path, the environment is installed. """ + if session.bin_paths is None: + session.log("Running with `--no-venv` so don't install anything...") + return False bin_files = list(Path(session.bin).glob("*")) sphinx_is_installed = any("sphinx-build" in ii.name for ii in bin_files) force_reinstall = "reinstall" in session.posargs From 360a7626fe5a37672c52037c71a49a0081e17139 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 10 Jan 2022 15:52:24 -0800 Subject: [PATCH 09/11] Address PR comments --- docs/conf.py | 3 ++- docs/contribute/topics.md | 55 ++++++++++++++++++++++++++++++--------- 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 4d53863c5..24ca7effc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -108,8 +108,9 @@ } html_sidebars = { - "contributing": [ + "contributing/index": [ "search-field", + "sidebar-nav-bs", "custom-template", ], # This ensures we test for custom sidebars } diff --git a/docs/contribute/topics.md b/docs/contribute/topics.md index a2a2a1cc3..8909f3d2b 100644 --- a/docs/contribute/topics.md +++ b/docs/contribute/topics.md @@ -114,27 +114,41 @@ The [Quick Reference](https://www.w3.org/WAI/WCAG21/quickref) may provide lighter reading. ::: -### Run an accessibility audit locally +### Errors in CI/CD and what to do -To run the accessibility problem finder locally: +We have a list of **known accessibility problems** in the file `docs/scripts/a11y-roadmap.txt`. +This contains a list of errors that we aim to fix in the future, and that **do not cause tests to fail**. -```console -$ nox -s compile # Compile the theme assets -$ nox -s docs # Build the documentation -$ python docs/scripts/a11y.py # Run a helper script for an accessibility audit -``` +When a pa11y accessibility audit is run in our CI/CD, it checks for any errors that are _not_ on this list, and if it finds them it will cause the job to error. -The output of the last command includes: +When you see an error in your CI/CD job, look at the logs under the `Run accessibility audit` job. +You should see an output that looks like this: -- a short summary of the current state of the accessibility rules we are trying to maintain -- local paths to JSON and HTML reports which contain all of the issues found +``` +JSON: /tmp/pa11y/pa11y-864/pa11y-ci-results.json +Roadmap: /home/runner/work/pydata-sphinx-theme/pydata-sphinx-theme/docs/a11y-roadmap.txt +not on roadmap: + WCAG2AA.Principle2.Guideline2_4.2_4_1.G1,G123,G124.NoSuchID: 4 +on roadmap: + WCAG2AA.Principle1.Guideline1_3.1_3_1.H39.3.LayoutTable: 1 + WCAG2AA.Principle1.Guideline1_3.1_3_1.H43,H63: 1 + WCAG2AA.Principle1.Guideline1_3.1_3_1.H43.HeadersRequired: 1 + WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail: 1828 + WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2: 48 + WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.EmptyNoId: 9 +passed: false +total errors: 1892 +``` + +The problems that caused an error are in the `not on roadmap` section. +Anything that is "not on the roadmap" is an error we have unexpectedly introduced in the PR. +These should be identified and fixed. ### Fix accessibility errors -Start by checking for issues on the -[accessibility roadmap](https://github.com/pydata/pydata-sphinx-theme/blob/master/docs/a11y-roadmap.txt). +We keep a list of **known accessibility issues** in the {download}`accessibility roadmap <../scripts/a11y-roadmap.txt>`. These are issues which are currently flagged by the toolset, but that have not yet -been fixed. If that file is empty (or just comments), hooray! +been fixed. To start working on one of the accessibility roadmap items, comment out one of the lines in `docs/a11y-roadmap.txt`, and re-run the audit to establish a baseline. @@ -142,6 +156,21 @@ lines in `docs/a11y-roadmap.txt`, and re-run the audit to establish a baseline. Then, fix the issue in either the HTML templates, CSS, or python code, and re-run the audit until it is fixed. +### Run an accessibility audit locally + +To run the accessibility problem finder locally: + +```console +$ nox -s compile # Compile the theme assets +$ nox -s docs # Build the documentation +$ python docs/scripts/a11y.py # Run a helper script for an accessibility audit +``` + +The output of the last command includes: + +- a short summary of the current state of the accessibility rules we are trying to maintain +- local paths to JSON and HTML reports which contain all of the issues found + ## Change fonts Three "styles" of the [FontAwesome 5 Free](https://fontawesome.com/icons?m=free) From 503e7f9e74a940cbe716dd49e79c917aa3207ff4 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 11 Jan 2022 13:23:43 +0100 Subject: [PATCH 10/11] Update docs/conf.py --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 24ca7effc..a22633757 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -108,7 +108,7 @@ } html_sidebars = { - "contributing/index": [ + "contribute/index": [ "search-field", "sidebar-nav-bs", "custom-template", From f77c74134ac99de5446ca1b432169ca2d0cc18f1 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Tue, 11 Jan 2022 07:22:44 -0800 Subject: [PATCH 11/11] Add back custom template --- docs/_templates/custom-template.html | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 docs/_templates/custom-template.html diff --git a/docs/_templates/custom-template.html b/docs/_templates/custom-template.html new file mode 100644 index 000000000..0ed45ec1c --- /dev/null +++ b/docs/_templates/custom-template.html @@ -0,0 +1,6 @@ +
+ This is a community-supported theme. + If you'd like to contribute, + check out our GitHub repository + Your contributions are welcome! +