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 index be9854c83..0ed45ec1c 100644 --- a/docs/_templates/custom-template.html +++ b/docs/_templates/custom-template.html @@ -1,6 +1,6 @@
- This is a community-supported theme. - If you'd like to contribute, - check out our GitHub repository - Your contributions are welcome! + 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..a22633757 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", @@ -107,6 +107,14 @@ }, } +html_sidebars = { + "contribute/index": [ + "search-field", + "sidebar-nav-bs", + "custom-template", + ], # This ensures we test for custom sidebars +} + html_context = { "github_user": "pandas-dev", @@ -115,6 +123,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..b397ec748 --- /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/pydata_sphinx_theme/assets/*` with +[webpack](https://webpack.js.org/). The main entrypoints are: + +- 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/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/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. + +```{toctree} +:maxdepth: 2 +setup +topics +manual +``` diff --git a/docs/contribute/manual.md b/docs/contribute/manual.md new file mode 100644 index 000000000..7da89c758 --- /dev/null +++ b/docs/contribute/manual.md @@ -0,0 +1,76 @@ +(manual-environment)= + +# Set up a manual development environment + +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 + +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..aed420f18 --- /dev/null +++ b/docs/contribute/setup.md @@ -0,0 +1,163 @@ +# 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 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` + +`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. + +:::{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. + +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. + +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 docs/_build/html/ +``` + +This will print a local URL that you can open in a browser to explore the HTML files. + +### 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..8909f3d2b --- /dev/null +++ b/docs/contribute/topics.md @@ -0,0 +1,225 @@ +# 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`. + +:::{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: + +```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 --no-venv +``` + +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. +::: + +### Errors in CI/CD and what to do + +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**. + +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. + +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: + +``` +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 + +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. + +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. + +### 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) +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..0a1d9d6c7 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,22 +1,57 @@ 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. + """ + 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 + should_install = not sphinx_is_installed or force_reinstall + if should_install: + session.log("Installing fresh environment...") + else: + session.log("Skipping environment install...") + return should_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",