diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index e8ad847b8..6c746af0f 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,7 +1,7 @@ // container instruction for codespace users { "name": "Python 3", - "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye", + "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye", "features": { "ghcr.io/devcontainers-contrib/features/nox:2": {}, "ghcr.io/devcontainers-contrib/features/pre-commit:2": {}, diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index cf0f3e0f2..66ee72636 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -5,7 +5,7 @@ default_language_version: repos: - repo: https://github.com/pre-commit/mirrors-prettier - rev: v2.7.1 + rev: v3.0.3 hooks: - id: prettier # Exclude the HTML, since it doesn't understand Jinja2 diff --git a/docs/_static/custom-icon.js b/docs/_static/custom-icon.js index cd949b3b7..bc64dd6b9 100644 --- a/docs/_static/custom-icon.js +++ b/docs/_static/custom-icon.js @@ -12,5 +12,5 @@ FontAwesome.library.add( "e001", // unicode codepoint - private use area "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z", // svg path (https://simpleicons.org/icons/pypi.svg) ], - }) + }), ); diff --git a/docs/community/contributors.md b/docs/community/contributors.md deleted file mode 100644 index e9bd63555..000000000 --- a/docs/community/contributors.md +++ /dev/null @@ -1,20 +0,0 @@ -# Contributors to this theme - -This theme is supported and developed by various members of [the PyData community](https://pydata.org). - -## Collaborators on the repository - -Here is a grid of collaborators on our GitHub repository. -We don't yet have formal "team definitions" so this is mostly a reflection of who has commit rights to the repository. - -```{gallery-grid} ../_static/contributors.yaml -:class-card: text-center -``` - -## Financial support - -Support and development for this theme has been funded by one [NumFocus Small Development Grant](https://numfocus.org/programs/small-development-grants) on behalf of several communities in the PyData ecosystem. - -## Theme logo - -Thanks to [@drammock](https://github.com/drammock) for the initial design of the theme logo. diff --git a/docs/community/contributors.rst b/docs/community/contributors.rst new file mode 100644 index 000000000..a6429225c --- /dev/null +++ b/docs/community/contributors.rst @@ -0,0 +1,23 @@ +Contributors to this theme +========================== + +This theme is supported and developed by various members of `the PyData community `__. + +Collaborators on the repository +------------------------------- + +Here is a grid of collaborators on our GitHub repository. +We don't yet have formal "team definitions" so this is mostly a reflection of who has commit rights to the repository. + +.. gallery-grid:: ../_static/contributors.yaml + :class-card: text-center + +Financial support +----------------- + +Support and development for this theme has been funded by one `NumFocus Small Development Grant `__ on behalf of several communities in the PyData ecosystem. + +Theme logo +---------- + +Thanks to `@drammock `__ for the initial design of the theme logo. diff --git a/docs/community/index.md b/docs/community/index.md deleted file mode 100644 index 220c4e6c5..000000000 --- a/docs/community/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -myst: - html_meta: - "description lang=en": "How to become a contributor to the pydata-sphinx-theme." ---- - -# Contributor Guide - -These pages contain information about the community that leads, supports, and develops this theme, including how you can contribute to the project. - -```{toctree} -:maxdepth: 2 -:caption: Contributor guide - -setup -structure -topics/index -``` - -```{toctree} -:caption: Team practices -:glob: -practices/* -``` - -```{toctree} -:maxdepth: 2 -:caption: About the project - -contributors -inspiration -``` diff --git a/docs/community/index.rst b/docs/community/index.rst new file mode 100644 index 000000000..42a6205a1 --- /dev/null +++ b/docs/community/index.rst @@ -0,0 +1,25 @@ +Contributor Guide +================= + +These pages contain information about the community that leads, supports, and develops this theme, including how you can contribute to the project. + +.. toctree:: + :maxdepth: 2 + :caption: Contributor guide + + setup + structure + topics/index + +.. toctree:: + :caption: Team practices + :glob: + + practices/* + +.. toctree:: + :maxdepth: 2 + :caption: About the project + + contributors + inspiration diff --git a/docs/community/inspiration.md b/docs/community/inspiration.md deleted file mode 100644 index 91f017d1d..000000000 --- a/docs/community/inspiration.md +++ /dev/null @@ -1,30 +0,0 @@ -# Inspiration for design and UX - -To build this theme we drew inspiration from other great projects on the web that we would like to acknowledge here. -When making new decisions about design and UI/UX, we often consult these themes to see what they're doing. - -```{gallery-grid} -:grid-columns: 1 2 2 3 -:class-container: text-center -- title: "**GitBook**" - link: https://docs.gitbook.com/ - image: https://avatars.githubusercontent.com/u/7111340?s=280&v=4 -- title: "**Metaflow**" - image: https://repository-images.githubusercontent.com/209120637/00b39080-1ddc-11ea-8710-59b484540700 - link: https://docs.metaflow.org/ -- title: "**Furo**" - image: https://avatars.githubusercontent.com/u/3275593?v=4 - link: https://pradyunsg.me/furo/quickstart -- title: "**Docker**" - link: https://docs.docker.com/ - image: https://www.docker.com/wp-content/uploads/2022/03/vertical-logo-monochromatic.png -- title: "**PyTorch**" - link: https://pytorch.org/docs/stable/index.html - image: https://pytorch.org/assets/images/pytorch-logo.png -- title: "**Docasaurus**" - link: https://docusaurus.io/docs - image: https://d33wubrfki0l68.cloudfront.net/c088b7acfcf11100903c44fe44f2f2d7e0f30531/47727/img/docusaurus.svg -- title: "**Material for MkDocs**" - link: https://squidfunk.github.io/mkdocs-material/getting-started/ - image: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/src/.icons/logo.svg -``` diff --git a/docs/community/inspiration.rst b/docs/community/inspiration.rst new file mode 100644 index 000000000..feea527a8 --- /dev/null +++ b/docs/community/inspiration.rst @@ -0,0 +1,31 @@ +Inspiration for design and UX +============================= + +To build this theme we drew inspiration from other great projects on the web that we would like to acknowledge here. +When making new decisions about design and UI/UX, we often consult these themes to see what they're doing. + +.. gallery-grid:: + :grid-columns: 1 2 2 3 + :class-container: text-center + + - title: "**GitBook**" + link: https://docs.gitbook.com/ + image: https://avatars.githubusercontent.com/u/7111340?s=280&v=4 + - title: "**Metaflow**" + image: https://repository-images.githubusercontent.com/209120637/00b39080-1ddc-11ea-8710-59b484540700 + link: https://docs.metaflow.org/ + - title: "**Furo**" + image: https://avatars.githubusercontent.com/u/3275593?v=4 + link: https://pradyunsg.me/furo/quickstart + - title: "**Docker**" + link: https://docs.docker.com/ + image: https://www.docker.com/wp-content/uploads/2022/03/vertical-logo-monochromatic.png + - title: "**PyTorch**" + link: https://pytorch.org/docs/stable/index.html + image: https://pytorch.org/assets/images/pytorch-logo.png + - title: "**Docasaurus**" + link: https://docusaurus.io/docs + image: https://d33wubrfki0l68.cloudfront.net/c088b7acfcf11100903c44fe44f2f2d7e0f30531/47727/img/docusaurus.svg + - title: "**Material for MkDocs**" + link: https://squidfunk.github.io/mkdocs-material/getting-started/ + image: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/src/.icons/logo.svg diff --git a/docs/community/practices/merge.md b/docs/community/practices/merge.rst similarity index 91% rename from docs/community/practices/merge.md rename to docs/community/practices/merge.rst index 03effa8ae..542163af9 100644 --- a/docs/community/practices/merge.md +++ b/docs/community/practices/merge.rst @@ -1,4 +1,5 @@ -# Merge and review policy +Merge and review policy +======================= Our policy for merging and reviewing describes how we review one another's work, and when we allow others to merge changes into our main codebase. It tries to balance a few goals: @@ -16,7 +17,8 @@ We follow these guidelines to achieve these goals: - It's important to share information, so give your best effort at telling others about the work that you're doing. - It's best to discuss and agree on important decisions at a high level before implementation, so give the best effort at providing time and invitation for others to provide feedback. -## Policy for moderate changes +Policy for moderate changes +--------------------------- These are changes that make modest changes to new or existing functionality, but that aren't going to significantly change the default behavior of the theme, user configuration, etc. This is the majority of changes that we make. @@ -31,14 +33,16 @@ They can be merged when the above conditions are met, and one of these things ha - The PR has at least one approval from a core maintainer that isn't the PR author - The PR author has signaled their intent to merge unless there are objections, and 48 hours have passed since that comment. -## Policy for major new features and breaking changes +Policy for major new features and breaking changes +-------------------------------------------------- These are changes that significantly alter the experience of the user, or that add significant complexity to the codebase. All the above, but PRs **must** have approval from at least one other core maintainer before merging. In addition, the PR author should put extra effort into ensuring that the relevant stakeholders are notified about a change, so they can gauge its impact and provide feedback. -## Policy For minor changes and bugfixes +Policy For minor changes and bugfixes +------------------------------------- These are small changes that might be noticeable to the user, but in a way that is clearly an improvement. They generally shouldn't touch too many lines of code. diff --git a/docs/community/practices/release.md b/docs/community/practices/release.rst similarity index 51% rename from docs/community/practices/release.md rename to docs/community/practices/release.rst index 6b4617a40..003594443 100644 --- a/docs/community/practices/release.md +++ b/docs/community/practices/release.rst @@ -1,8 +1,10 @@ -# Making releases +Making releases +=============== -(policies:release)= +.. _policies-release: -## Our goals +Our goals +--------- Our release policy describes how we decide when to make a new public release of the theme so that other projects may use new features and improvements. It tries to balance these goals: @@ -11,33 +13,37 @@ It tries to balance these goals: - Do not surprise people (especially with negative surprises) and provide time for projects to provide feedback about upcoming features. - Minimize the toil and complexity associated with releases, and reduce information silos and bottlenecks associated with them. -(releases:when)= +.. _releases-when: -## When to make a release +When to make a release +---------------------- Anybody is encouraged to make a new release if: - It has been more than a month since the last release. - OR a significant change has been made to our code that warrants a release. -- AND there are no open issues with a [{guilabel}`block-release`](https://github.com/pydata/pydata-sphinx-theme/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ablock-release) label. +- AND there are no open issues with a :guilabel:`impact: block-release` label. -### Release candidates +Release candidates +^^^^^^^^^^^^^^^^^^ -If a release includes complex or many changes (especially in JavaScript), make a `release candidate` and ask for feedback from users. +If a release includes complex or many changes (especially in JavaScript), make a ``release candidate`` and ask for feedback from users. This is important because we do not test much of the CSS and JavaScript-based functionality in our testing infrastructure. After a week or so, if there are no blocking issues that have been opened since the Release Candidate, we can make a full release. -## Process for making a release +Process for making a release +---------------------------- This theme uses GitHub tags and releases to automatically push new releases to PyPI. Follow these steps to make a release: -- (optionally) **Create a [GitHub milestones](https://github.com/pydata/pydata-sphinx-theme/milestones)** to organize the issues that should be resolved as part of a new release. -- **Decide if it's time** to make a release be reading [](releases:when) and decide if it is time for a release. -- **Copy the release checklist into a new issue**. We have [a release checklist in our wiki](https://github.com/pydata/pydata-sphinx-theme/wiki/Release-checklist#release-instructions). +- (optionally) **Create a `GitHub milestones `__** to organize the issues that should be resolved as part of a new release. +- **Decide if it's time** to make a release be reading `releases-when`_ and decide if it is time for a release. +- **Copy the release checklist into a new issue**. We have `a release checklist in our wiki `_. - **Complete the checklist**. That's it! -## Choosing a version increment +Choosing a version increment +---------------------------- -We use [semantic versioning](https://semver.org/) to decide whether it's a major, minor, or patch bump. Before we have released `1.0`, treat minor versions as breaking releases, and patch versions as feature / patch releases. **If this is a release candidate**, tag it like `0.1rc1`. +We use `semantic versioning `__ to decide whether it's a major, minor, or patch bump. Before we have released ``1.0``, treat minor versions as breaking releases, and patch versions as feature / patch releases. **If this is a release candidate**, tag it like ``0.1rc1``. diff --git a/docs/community/practices/versions.md b/docs/community/practices/versions.md deleted file mode 100644 index 18d7a7364..000000000 --- a/docs/community/practices/versions.md +++ /dev/null @@ -1,36 +0,0 @@ -# Supported Python and Sphinx versions - -Python and Sphinx are the two primary dependencies of this theme. -We have particular practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes). - -## Supported Python versions - -For releases of Python, we aim to follow this approach[^1]: - -> For a new major/minor release of this theme, we support any minor Python versions released in the last 3.5 years (42 months), as defined in [the EOL schedule for Python](https://endoflife.date/python)[^2]. - -We define "support" as testing against each of these versions so that users can be assured they will not trigger any bugs. - -For example, if we made a minor release tomorrow, we'd [look at the EOL schedule for Python](https://endoflife.date/python) and support all the versions that fall within a 3.5-year window. - -[^1]: Our support for Python versions is inspired by [NEP 029](https://numpy.org/neps/nep-0029-deprecation_policy.html). -[^2]: These policies are goals, not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we cannot do so. We welcome contributions from others to help us more sustainably meet these goals! - -## Supported Sphinx versions - -For supported versions of Sphinx, we aim to follow this approach: - -> We support the latest released version of Sphinx that is **older than 6 months**. -> We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed[^2]. - -When a new pre-release of Sphinx is released, we should follow these steps: - -- Ensure that our tests are passing. We run our tests with any **pre-releases** of Sphinx, so we can test major errors quickly and make the necessary changes. -- [Look at the Sphinx Changelog](https://www.sphinx-doc.org/en/master/changes.html) and make sure there are no changes that might break things that aren't captured by our tests. -- [Look at the deprecated API changes](https://www.sphinx-doc.org/en/master/extdev/deprecated.html) and make sure there are no changes that might break things that aren't captured by our tests. -- [Look at the docutils changelog](https://docutils.sourceforge.io/RELEASE-NOTES.html) in case there's a new docutils version supported that breaks something. - -```{note} -This theme does not pin the upper version of Sphinx that it supports. -If a Sphinx release causes major breaking changes for our users, and we do not have the capacity to update our code and release a fix, we may temporarily pin the upper bound of Sphinx we support until this is fixed. -``` diff --git a/docs/community/practices/versions.rst b/docs/community/practices/versions.rst new file mode 100644 index 000000000..ca006df6c --- /dev/null +++ b/docs/community/practices/versions.rst @@ -0,0 +1,42 @@ +Supported Python and Sphinx versions +==================================== + +Python and Sphinx are the two primary dependencies of this theme. +We have particular practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes). + +Supported Python versions +------------------------- + +For releases of Python, we aim to follow this approach [1]: + + For a new major/minor release of this theme, we support any minor Python versions released in the last 3.5 years (42 months), as defined in `the EOL schedule for Python `__ [2]. + +We define "support" as testing against each of these versions so that users can be assured they will not trigger any bugs. + +For example, if we made a minor release tomorrow, we'd `look at the EOL schedule for Python `__ and support all the versions that fall within a 3.5-year window. + +Supported Sphinx versions +------------------------- + +For supported versions of Sphinx, we aim to follow this approach: + + We support the latest released version of Sphinx that is **older than 6 months**. + We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed [2]. + +When a new pre-release of Sphinx is released, we should follow these steps: + +- Ensure that our tests are passing. We run our tests with any **pre-releases** of Sphinx, so we can test major errors quickly and make the necessary changes. +- `Look at the Sphinx Changelog `__ and make sure there are no changes that might break things that aren't captured by our tests. +- `Look at the deprecated API changes `__ and make sure there are no changes that might break things that aren't captured by our tests. +- `Look at the docutils changelog `__ in case there's a new docutils version supported that breaks something. + +.. note:: + + This theme does not pin the upper version of Sphinx that it supports. + If a Sphinx release causes major breaking changes for our users, and we do not have the capacity to update our code and release a fix, we may temporarily pin the upper bound of Sphinx we support until this is fixed. + +.. rubric:: Footnotes + +.. [1] Our support for Python versions is inspired by `NEP 029 `__. + +.. [2] These policies are goals, not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we cannot do so. We welcome contributions from others to help us more sustainably meet these goals! diff --git a/docs/community/setup.md b/docs/community/setup.md deleted file mode 100644 index 309e53ece..000000000 --- a/docs/community/setup.md +++ /dev/null @@ -1,194 +0,0 @@ -# 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 [](topics/manual-dev.md). - -## 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 documentation is built and deployed to make it easier to review the changes in the PR. -To access this, click on the {{ rtd }} preview in the CI/CD jobs. - -The sections below cover the steps to take in more detail. - -## Clone the repository - -First off you'll need your 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/) compiles web assets in an automated way. -- [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. -- [pandoc](https://pandoc.org/) the universal document converter. - -In particular, `nox` can be used to automatically create isolated local development environments with all 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 [](topics/manual-dev.md). -``` - -### Setup `nox` - -To start, install `nox`: - -```console -$ pip install nox -``` - -You can call `nox` from the command line 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 only 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 previously created 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 (build the docs and compile JS/CSS assets) 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, making 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. There is a lightweight fixture defined -in the `test_build.py` script that makes it straightforward to run a Sphinx build using -this theme and inspect the results. There are also several automated accessibility checks in -`test_a11y.py`. - -```{warning} -Currently, the automated accessibility tests check the Kitchen Sink page only. -We are working on extending coverage to the rest of the theme. -``` - -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 build tests with `nox`, run the following command: - -```console -$ nox -s test -``` - -To run the accessibility checks: - -```console -$ nox -s a11y -``` diff --git a/docs/community/setup.rst b/docs/community/setup.rst new file mode 100644 index 000000000..48b386cb7 --- /dev/null +++ b/docs/community/setup.rst @@ -0,0 +1,204 @@ +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 topics/manual-dev.md. + +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 documentation is built and deployed to make it easier to review the changes in the PR. +To access this, click on the |rtd| preview in the CI/CD jobs. + +The sections below cover the steps to take in more detail. + +Clone the repository +-------------------- + +First off you'll need your 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 `__ for more information. +2. **Clone the repository locally** so that you have a local copy to work from: + + .. code-block:: 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 `__ compiles web assets in an automated way. +- `pre-commit `__ for automatically enforcing code standards and quality checks before commits. +- `nox `__ for automating common development tasks. +- `pandoc `__ the universal document converter. + +In particular, ``nox`` can be used to automatically create isolated local development environments with all 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 [](topics/manual-dev.md). +``` + +Setup ``nox`` +^^^^^^^^^^^^^ + +To start, install ``nox``: + +.. code-block:: console + + pip install nox + +You can call ``nox`` from the command line 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 only 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: + +.. code-block:: console + + pip install pre-commit + +then navigate to this repository's folder and activate it like so: + +.. code-block:: 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: + +.. code-block:: 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 `__ with: + +.. code-block:: 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 previously created 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: + +.. code-block:: 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 (build the docs and compile JS/CSS assets) 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: + +.. code-block:: console + + nox -s docs-live + +When working on the theme, making 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. There is a lightweight fixture defined +in the ``test_build.py`` script that makes it straightforward to run a Sphinx build using +this theme and inspect the results. There are also several automated accessibility checks in +``test_a11y.py``. + +.. warning:: + + Currently, the automated accessibility tests check the Kitchen Sink page only. + We are working on extending coverage to the rest of the theme. + +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 build tests with ``nox``, run the following command: + +.. code-block:: console + + nox -s test + +To run the accessibility checks: + +.. code-block:: console + + nox -s a11y diff --git a/docs/community/structure.md b/docs/community/structure.md deleted file mode 100644 index f16297169..000000000 --- a/docs/community/structure.md +++ /dev/null @@ -1,26 +0,0 @@ -# Structure of this theme - -## 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 entry points are: - -- CSS: `src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss` - - - the main part of the theme assets - - customizes [Bootstrap](https://getbootstrap.com/) with [Sass](https://sass-lang.com) - -- JS: `src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.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/` diff --git a/docs/community/structure.rst b/docs/community/structure.rst new file mode 100644 index 000000000..2baa13a54 --- /dev/null +++ b/docs/community/structure.rst @@ -0,0 +1,29 @@ +Structure of this theme +======================= + +Location and structure of documentation +--------------------------------------- + +The documentation for this theme is in the ``docs/`` folder. +It is structured as a `Sphinx documentation site `. +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 `__. The main entry points are: + +- CSS: ``src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss`` + + - the main part of the theme assets + - customizes `Bootstrap `__ with `Sass `__ + +- JS: ``src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.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/`` diff --git a/docs/community/topics/accessibility.md b/docs/community/topics/accessibility.md deleted file mode 100644 index 4e4485d9c..000000000 --- a/docs/community/topics/accessibility.md +++ /dev/null @@ -1,20 +0,0 @@ -# Accessibility checks - -```{note} -April-2023: we are currently -[re-evaluating how we do accessibility checks](https://github.com/pydata/pydata-sphinx-theme/issues/1168) -and reporting, so this may change soon. -``` - -In general, accessibility-checking tools can find a limited number of common HTML patterns which -assistive technology can't help users understand. - -## Accessibility checks as part of our development process - -We run a [Lighthouse](https://developers.google.com/web/tools/lighthouse) job in our CI/CD, which generates a "score" for all pages in our **Kitchen Sink** example documentation. -The configuration for Lighthouse can be found in the `.github/workflows/lighthouserc.json` file. - -For more information about configuring Lighthouse, see [the Lighthouse documentation](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md). -For more information about Accessibility in general, see [](../../user_guide/accessibility.md). - -We have also recently added automated tests using [Playwright](https://playwright.dev/python/) and [axe-core](https://github.com/dequelabs/axe-core) to improve our accessibility testing and reporting. diff --git a/docs/community/topics/accessibility.rst b/docs/community/topics/accessibility.rst new file mode 100644 index 000000000..cc366e250 --- /dev/null +++ b/docs/community/topics/accessibility.rst @@ -0,0 +1,22 @@ +Accessibility checks +==================== + +.. note:: + + April-2023: we are currently + `re-evaluating how we do accessibility checks `__ + and reporting, so this may change soon. + +In general, accessibility-checking tools can find a limited number of common HTML patterns which +assistive technology can't help users understand. + +Accessibility checks as part of our development process +------------------------------------------------------- + +We run a `Lighthouse `__ job in our CI/CD, which generates a "score" for all pages in our **Kitchen Sink** example documentation. +The configuration for Lighthouse can be found in the ``.github/workflows/lighthouserc.json`` file. + +For more information about configuring Lighthouse, see `the Lighthouse documentation `__. +For more information about Accessibility in general, see _`../../user_guide/accessibility.rst`. + +We have also recently added automated tests using `Playwright `__ and `axe-core `__ to improve our accessibility testing and reporting. diff --git a/docs/community/topics/assets.md b/docs/community/topics/assets.md deleted file mode 100644 index c893c6348..000000000 --- a/docs/community/topics/assets.md +++ /dev/null @@ -1,56 +0,0 @@ -# Web assets (CSS/JS/Fonts) - -This theme includes several web assets to ease development and design. -The configuration for our asset compilation is in `webpack.config.js`. - -## Compile and bundle assets - -When assets are compiled, static versions are placed in various places in the theme's static folder: - -``` -src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static -``` - -For many assets, a `` is generated and appended to the end of its 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. - -To compile the assets and bundle them with the theme, run this command: - -```console -$ nox -s compile -``` - -## Styles (SCSS) and Scripts (JS) - -There are two relevant places for CSS/JS assets: - -- `src/pydata_sphinx_theme/assets/styles` has source files for SCSS assets. These will be compiled to CSS. -- `src/pydata_sphinx_theme/assets/scripts` has source files for JS assets. These will be compiled to JS and import several vendored libraries (like Bootstrap). -- `src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static` has compiled versions of these assets (e.g. CSS files). This folder is not tracked in `.git` history, but it is bundled with the theme's distribution. - -## Vendored scripts - -We vendor several packages in addition to our own CSS and JS. -For example, Bootstrap, JQuery, and Popper. -This is configured in the `webpack.config.js` file, and imported in the respective `SCSS` or `JS` file in our assets folder. - -## FontAwesome icons - -Three "styles" of the [FontAwesome 6 Free](https://fontawesome.com/icons?m=free) -icon font are used for {ref}`icon links ` and admonitions and is -the only `vendored` font. - -- It is managed as a dependency in `package.json` -- Copied directly into the site statics at compilation, including licenses -- Partially preloaded to reduce flicker and artifacts of early icon renders -- Configured in `webpack.config.js` - -## Jinja macros - -Our Webpack build generates a collection of [Jinja macros](https://jinja.palletsprojects.com/en/3.0.x/templates/#macros) in the `static/webpack-macros.html` file. - -These macros are imported in the main `layout.html` file, and then inserted at various places on the page to link the static assets. - -Some assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload), meaning that the browser begins requesting these resources before they're needed. -In particular, our JavaScript assets are preloaded in ``, and the scripts are loaded at the end of ``. diff --git a/docs/community/topics/assets.rst b/docs/community/topics/assets.rst new file mode 100644 index 000000000..a6f172ac0 --- /dev/null +++ b/docs/community/topics/assets.rst @@ -0,0 +1,62 @@ +Web assets (CSS/JS/Fonts) +========================= + +This theme includes several web assets to ease development and design. +The configuration for our asset compilation is in ``webpack.config.js``. + +Compile and bundle assets +------------------------- + +When assets are compiled, static versions are placed in various places in the theme's static folder: + +.. code-block:: + + src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static + +For many assets, a ```` is generated and appended to the end of its 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. + +To compile the assets and bundle them with the theme, run this command: + +.. code-block:: console + + nox -s compile + +Styles (SCSS) and Scripts (JS) +------------------------------ + +There are two relevant places for CSS/JS assets: + +- ``src/pydata_sphinx_theme/assets/styles`` has source files for SCSS assets. These will be compiled to CSS. +- ``src/pydata_sphinx_theme/assets/scripts`` has source files for JS assets. These will be compiled to JS and import several vendored libraries (like Bootstrap). +- ``src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static`` has compiled versions of these assets (e.g. CSS files). This folder is not tracked in ``.git`` history, but it is bundled with the theme's distribution. + +Vendored scripts +---------------- + +We vendor several packages in addition to our own CSS and JS. +For example, Bootstrap, JQuery, and Popper. +This is configured in the ``webpack.config.js`` file, and imported in the respective ``SCSS`` or ``JS`` file in our assets folder. + +FontAwesome icons +----------------- + +Three "styles" of the `FontAwesome 6 Free `__ +icon font are used for :ref:`icon links ` and admonitions and is +the only ``vendored`` font. + +- It is managed as a dependency in ``package.json`` +- Copied directly into the site statics at compilation, including licenses +- Partially preloaded to reduce flicker and artifacts of early icon renders +- Configured in ``webpack.config.js`` + +Jinja macros +------------ + +Our Webpack build generates a collection of `Jinja macros `__ in the ``static/webpack-macros.html`` file. + +These macros are imported in the main ``layout.html`` file, and then inserted at various places on the page to link the static assets. + +Some assets `are "preloaded" `__, meaning that the browser begins requesting these resources before they're needed. +In particular, our JavaScript assets are preloaded in ````, and the scripts are loaded at the end of ````. diff --git a/docs/community/topics/attribution.md b/docs/community/topics/attribution.rst similarity index 57% rename from docs/community/topics/attribution.md rename to docs/community/topics/attribution.rst index bfbae9616..4d4b7d1a6 100644 --- a/docs/community/topics/attribution.md +++ b/docs/community/topics/attribution.rst @@ -1,6 +1,7 @@ -# Ignore formatting commits with `git blame` +Ignore formatting commits with `git blame` +========================================== -When making commits that are strictly formatting/style changes (e.g., after running a new version of black or running pyupgrade after dropping an old Python version), add the commit hash to `.git-blame-ignore-revs`, so `git blame` can ignore the change. +When making commits that are strictly formatting/style changes (e.g., after running a new version of black or running pyupgrade after dropping an old Python version), add the commit hash to ``.git-blame-ignore-revs``, so ``git blame`` can ignore the change. For more details, see: diff --git a/docs/community/topics/config.md b/docs/community/topics/config.md deleted file mode 100644 index a78725470..000000000 --- a/docs/community/topics/config.md +++ /dev/null @@ -1,30 +0,0 @@ -# Update Sphinx configuration during the build - -Sometimes you want to update configuration values _during a build_. -For example, if you want to set a default if the user hasn't provided a value, or if you want to move the value from one keyword to another for a deprecation. - -Here are some tips to do this the "right" way in Sphinx. - -## Update config: use `app.config` - -For example, `app.config.foo = "bar"`. -For some reason, when Sphinx sets things it directly uses `__dict__`, but this doesn't seem to be different from the pattern described here. - -## Update theme options: use `app.builder.theme_options` - -For example, `app.builder.theme_options["logo"] = {"text": "Foo"}`. - -## Check if a user has provided a default: `app.config._raw_config` - -The `app.config._raw_config` attribute contains all of the **user-provided values**. -Use this if you want to check whether somebody has manually specified something. -For example, `"somekey" in app.config._raw_config` will be `False` if a user has _not_ provided that option. - -You can also check `app.config.overrides` for any CLI-provided overrides. - -We bundle both checks in a helper function called `_config_provided_by_user`. - -## Avoid the `config-inited` event - -This theme is activated **after** `config-inited` is triggered, so if you write an event that depends on it in this theme, then it will never occur. -The earliest event you can use is `builder-inited`. diff --git a/docs/community/topics/config.rst b/docs/community/topics/config.rst new file mode 100644 index 000000000..ec9f397cc --- /dev/null +++ b/docs/community/topics/config.rst @@ -0,0 +1,35 @@ +Update Sphinx configuration during the build +============================================ + +Sometimes you want to update configuration values *during a build*. +For example, if you want to set a default if the user hasn't provided a value, or if you want to move the value from one keyword to another for a deprecation. + +Here are some tips to do this the "right" way in Sphinx. + +Update config: use ``app.config`` +--------------------------------- + +For example, ``app.config.foo = "bar"``. +For some reason, when Sphinx sets things it directly uses ``__dict__``, but this doesn't seem to be different from the pattern described here. + +Update theme options: use ``app.builder.theme_options`` +------------------------------------------------------- + +For example, ``app.builder.theme_options["logo"] = {"text": "Foo"}``. + +Check if a user has provided a default: ``app.config._raw_config`` +------------------------------------------------------------------ + +The ``app.config._raw_config`` attribute contains all of the **user-provided values**. +Use this if you want to check whether somebody has manually specified something. +For example, ``"somekey" in app.config._raw_config`` will be ``False`` if a user has _not_ provided that option. + +You can also check ``app.config.overrides`` for any CLI-provided overrides. + +We bundle both checks in a helper function called ``_config_provided_by_user``. + +Avoid the ``config-inited`` event +--------------------------------- + +This theme is activated **after** ``config-inited`` is triggered, so if you write an event that depends on it in this theme, then it will never occur. +The earliest event you can use is ``builder-inited``. diff --git a/docs/community/topics/dependencies-js.md b/docs/community/topics/dependencies-js.md deleted file mode 100644 index 3887b360d..000000000 --- a/docs/community/topics/dependencies-js.md +++ /dev/null @@ -1,17 +0,0 @@ -# Update JavaScript dependencies and their versions - -There are two kinds of dependency definitions in this theme: - -- `package.json` contains the **base dependencies** for this theme. They are broken down into a few categories like `dependencies` and `devDependencies`. It is edited by the maintainers. -- `package-lock.json` contains the complete **frozen dependency chain** for this theme, including all sub-dependencies of our base dependencies. It is automatically generated. - -To update or add a JS dependency, follow these steps: - -1. **Edit `package.json`** by adding or modifying a dependency. -2. **Re-generate `package-lock.json`** in order to create a new set of frozen dependencies for the theme. To do this, run the following command from [the Sphinx Theme Builder](https://github.com/pradyunsg/sphinx-theme-builder). - - ``` - stb npm install --include=dev - ``` - -3. **Commit both files** to the repository. When new people pull in the latest commits, their `npm` environment will automatically update according to the new lockfile. diff --git a/docs/community/topics/dependencies-js.rst b/docs/community/topics/dependencies-js.rst new file mode 100644 index 000000000..3121ff9c0 --- /dev/null +++ b/docs/community/topics/dependencies-js.rst @@ -0,0 +1,18 @@ +Update JavaScript dependencies and their versions +================================================= + +There are two kinds of dependency definitions in this theme: + +- ``package.json`` contains the **base dependencies** for this theme. They are broken down into a few categories like ``dependencies`` and ``devDependencies``. It is edited by the maintainers. +- ``package-lock.json`` contains the complete **frozen dependency chain** for this theme, including all sub-dependencies of our base dependencies. It is automatically generated. + +To update or add a JS dependency, follow these steps: + +1. **Edit ``package.json``** by adding or modifying a dependency. +2. **Re-generate ``package-lock.json``** in order to create a new set of frozen dependencies for the theme. To do this, run the following command from `the Sphinx Theme Builder `__. + + .. code-block:: console + + stb npm install --include=dev + +3. **Commit both files** to the repository. When new people pull in the latest commits, their ``npm`` environment will automatically update according to the new lockfile. diff --git a/docs/community/topics/galleries.md b/docs/community/topics/galleries.md deleted file mode 100644 index 997a2d02e..000000000 --- a/docs/community/topics/galleries.md +++ /dev/null @@ -1,33 +0,0 @@ -# Galleries and the `gallery-grid` directive - -There are a few places where we use `sphinx-design` to generate "galleries" of grids with structured text and images. -We've created a little Sphinx directive to make it easier to repeat this process in our documentation and to avoid repeating ourselves too much. -It is located in the `docs/scripts/` folder in a dedicated module, and re-used throughout our documentation. - -## The example gallery - -This theme's documentation contains a gallery of sites that use this theme for their documentation. -The images are automatically generated during ReadTheDocs builds, but are **not** automatically generated on local or test builds (to save time). - -If you build the documentation locally without first generating these images you may get Sphinx warnings or errors, but this should be fine as long as the images build on ReadTheDocs tests. - -### Download gallery images locally - -If you'd like to build these images locally to preview in the theme, follow these steps: - -1. Install [playwright](https://playwright.dev/python/) and the Chromium browser add-on: - - ``` - $ pip install playwright - $ playwright install chromium - ``` - -2. Execute the gallery generation script from the repository root: - - ``` - $ python ./docs/scripts/generate_gallery_images.py - ``` - -:::{note} -The newly generated images will be pushed to the distant repository. -::: diff --git a/docs/community/topics/galleries.rst b/docs/community/topics/galleries.rst new file mode 100644 index 000000000..d316713b4 --- /dev/null +++ b/docs/community/topics/galleries.rst @@ -0,0 +1,35 @@ +Galleries and the ``gallery-grid`` directive +============================================ + +There are a few places where we use ``sphinx-design`` to generate "galleries" of grids with structured text and images. +We've created a little Sphinx directive to make it easier to repeat this process in our documentation and to avoid repeating ourselves too much. +It is located in the ``docs/scripts/`` folder in a dedicated module, and re-used throughout our documentation. + +The example gallery +------------------- + +This theme's documentation contains a gallery of sites that use this theme for their documentation. +The images are automatically generated during ReadTheDocs builds, but are **not** automatically generated on local or test builds (to save time). + +If you build the documentation locally without first generating these images you may get Sphinx warnings or errors, but this should be fine as long as the images build on ReadTheDocs tests. + +Download gallery images locally +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you'd like to build these images locally to preview in the theme, follow these steps: + +1. Install `playwright `__ and the Chromium browser add-on: + + .. code-block:: console + + pip install playwright + playwright install chromium + +2. Execute the gallery generation script from the repository root: + + .. code-block:: console + + python ./docs/scripts/generate_gallery_images.py + +.. note:: + + The newly generated images will be pushed to the distant repository. diff --git a/docs/community/topics/index.md b/docs/community/topics/index.rst similarity index 53% rename from docs/community/topics/index.md rename to docs/community/topics/index.rst index 4dabb31a2..f281ce185 100644 --- a/docs/community/topics/index.md +++ b/docs/community/topics/index.rst @@ -1,9 +1,10 @@ -# Topic guides +Topic guides +============ These guides cover specific topics that are relevant to contributing to this theme. -```{toctree} -:maxdepth: 2 -:glob: -* -``` +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/docs/community/topics/kitchen-sink.md b/docs/community/topics/kitchen-sink.md deleted file mode 100644 index 2a4b2b410..000000000 --- a/docs/community/topics/kitchen-sink.md +++ /dev/null @@ -1,8 +0,0 @@ -# Update our kitchen sink - -The [kitchen sink reference](../../examples/kitchen-sink/index.rst) is for demonstrating as much syntax and style for Sphinx builds as possible. -It is copied directly from the [`sphinx-themes.org` documentation](https://sphinx-themes.org/) so that we use standardized reference docs compared with other communities. -The source files for these pages are stored [in the `sphinx-themes.org` repository](https://github.com/sphinx-themes/sphinx-themes.org/raw/master/sample-docs/kitchen-sink/). - -To update the kitchen sink source files, there is a helper Python script that will loop through the known kitchen sink files and copy over the latest text. -To use it, run the following from the root of the repository: diff --git a/docs/community/topics/kitchen-sink.rst b/docs/community/topics/kitchen-sink.rst new file mode 100644 index 000000000..9e0b5adbc --- /dev/null +++ b/docs/community/topics/kitchen-sink.rst @@ -0,0 +1,9 @@ +Update our kitchen sink +======================= + +The `kitchen sink reference <../../examples/kitchen-sink/index.rst>`__ is for demonstrating as much syntax and style for Sphinx builds as possible. +It is copied directly from the `sphinx-themes.org documentation `__ so that we use standardized reference docs compared with other communities. +The source files for these pages are stored in `the sphinx-themes.org repository `__. + +To update the kitchen sink source files, there is a helper Python script that will loop through the known kitchen sink files and copy over the latest text. +To use it, run the following from the root of the repository: diff --git a/docs/community/topics/manual-dev.md b/docs/community/topics/manual-dev.md deleted file mode 100644 index 2b05d5888..000000000 --- a/docs/community/topics/manual-dev.md +++ /dev/null @@ -1,80 +0,0 @@ -(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 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/). - -## Install dependencies - -You must install `sphinx-theme-builder` and Pandoc. - -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]" -``` - -We use `nbsphinx` to support notebook (.ipynb) files in the documentation, which requires [installing Pandoc](https://pandoc.org/installing.html) at a system level (or within a Conda environment). - -## 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 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/community/topics/manual-dev.rst b/docs/community/topics/manual-dev.rst new file mode 100644 index 000000000..caef81d02 --- /dev/null +++ b/docs/community/topics/manual-dev.rst @@ -0,0 +1,89 @@ +.. _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 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 `__, `mamba `__, or `virtualenv `__. + +Install dependencies +-------------------- + +You must install ``sphinx-theme-builder`` and Pandoc. + +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): + +.. code-block:: console + + pip install "sphinx-theme-builder[cli]" + +We use ``nbsphinx`` to support notebook (.ipynb) files in the documentation, which requires `installing Pandoc `__ at a system level (or within a Conda environment). + +Clone the repository locally +---------------------------- + +First clone this repository from the ``pydata`` organization, or from a fork that you have created: + +.. code-block:: console + + git clone https://github.com/pydata/pydata-sphinx-theme + cd pydata-sphinx-theme + +Install this theme locally +-------------------------- + +Next, install this theme locally so that we have the necessary dependencies to build the documentation and testing suite: + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: console + + pytest diff --git a/docs/community/topics/nox.md b/docs/community/topics/nox.md deleted file mode 100644 index d62e5be57..000000000 --- a/docs/community/topics/nox.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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. diff --git a/docs/community/topics/nox.rst b/docs/community/topics/nox.rst new file mode 100644 index 000000000..67cbc4ad8 --- /dev/null +++ b/docs/community/topics/nox.rst @@ -0,0 +1,41 @@ +Using ``nox`` +============= + +Here are a few extra tips for using ``nox``. + +.. seealso:: + + The `nox command line documentation `__ 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: + +.. 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 + +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: + +.. code-block:: console + + nox --force-venv-backend none + +alternatively: + +.. code-block:: console + + nox --no-venv + +Using ``none`` will re-use your current global environment. +See `the nox documentation `__ for more details. diff --git a/docs/community/topics/page-metadata.md b/docs/community/topics/page-metadata.md deleted file mode 100644 index fab3eef4d..000000000 --- a/docs/community/topics/page-metadata.md +++ /dev/null @@ -1,31 +0,0 @@ -# Page-level configuration - -In some areas we support page-level configuration to control behavior on a per-page basis. -Try to make this configuration follow the `html_theme_options` structure of our configuration as much as possibl. -Begin them with `html_theme`, and separate "nested" configuration sections with periods (`.`). -This is [similar to how the TOML language defines nested configuration](https://toml.io/en/v1.0.0#keys). - -For example, to remove the secondary sidebar, we use a page metadata key like this: - -`````{tab-set} -````{tab-item} rST -```rst -:html_theme.sidebar_secondary.remove: true -``` -```` -````{tab-item} Markdown -```md ---- -html_theme.sidebar_secondary.remove: true ---- -``` -```` -````` - -Note how the period naturally separates nested sections, and looks very similar to what we'd expect if we put this in a Python dictionary in `conf.py`: - -```python -html_theme_options = { - "sidebar_secondary": {"remove": "true"} -} -``` diff --git a/docs/community/topics/page-metadata.rst b/docs/community/topics/page-metadata.rst new file mode 100644 index 000000000..44cbcf336 --- /dev/null +++ b/docs/community/topics/page-metadata.rst @@ -0,0 +1,33 @@ +Page-level configuration +======================== + +In some areas we support page-level configuration to control behavior on a per-page basis. +Try to make this configuration follow the ``html_theme_options`` structure of our configuration as much as possible. +Begin them with ``html_theme``, and separate "nested" configuration sections with periods (`.`). +This is `similar to how the TOML language defines nested configuration `. + +For example, to remove the secondary sidebar, we use a page metadata key like this: + +.. tab-set:: + + .. tab-item:: rST + + .. code-block:: rst + + :html_theme.sidebar_secondary.remove: true + + .. tab-item:: Markdown + + .. code-block:: md + + --- + html_theme.sidebar_secondary.remove: true + --- + +Note how the period naturally separates nested sections, and looks very similar to what we'd expect if we put this in a Python dictionary in ``conf.py``: + +.. code-block:: python + + html_theme_options = { + "sidebar_secondary": {"remove": "true"} + } diff --git a/docs/community/topics/pre-commit.md b/docs/community/topics/pre-commit.md deleted file mode 100644 index dc05b9d90..000000000 --- a/docs/community/topics/pre-commit.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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 -``` diff --git a/docs/community/topics/pre-commit.rst b/docs/community/topics/pre-commit.rst new file mode 100644 index 000000000..86795c5e4 --- /dev/null +++ b/docs/community/topics/pre-commit.rst @@ -0,0 +1,31 @@ +Using ``pre-commit`` +==================== + +Here are a few tips for using ``pre-commit``: + +Skip the pre-commit checks +-------------------------- + +Run the following command: + +.. code-block:: 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: + +.. code-block:: console + + pre-commit run --all-files + +.. note:: + + Alternatively + + .. code-block:: console + + pre-commit run -a diff --git a/docs/community/topics/pydata.md b/docs/community/topics/pydata.md deleted file mode 100644 index 038d2edf1..000000000 --- a/docs/community/topics/pydata.md +++ /dev/null @@ -1,11 +0,0 @@ -# PyData package support - -This theme is designed by and for the PyData community, and so there are a few places where we special-case support for packages in this community. - -We define CSS rules that ensure PyData content in Sphinx looks reasonable on both light and dark themes. -If we hear reports from maintainers that we could change something in this theme that would make their documentation look better, and if this change is sustainable for us, then we should do so. - -We store our PyData-specific SCSS in two relevant files, both in the `src/pydata_sphinx_theme/assets/styles/` folder: - -- `extensions/_execution.scss` - styles for Sphinx libraries that execute and insert code into the documentation. For example, MyST-NB, Jupyter Sphinx, and the Matplotlib `plot` directive. Most PyData support should go here via generic improvements that all packages benefit from. -- `extensions/_pydata.scss` - styles for specific libraries in the PyData ecosystem. In general we should try to keep this minimal because it is mostly special-casing single library quirks. diff --git a/docs/community/topics/pydata.rst b/docs/community/topics/pydata.rst new file mode 100644 index 000000000..351d6a03d --- /dev/null +++ b/docs/community/topics/pydata.rst @@ -0,0 +1,12 @@ +PyData package support +====================== + +This theme is designed by and for the PyData community, and so there are a few places where we special-case support for packages in this community. + +We define CSS rules that ensure PyData content in Sphinx looks reasonable on both light and dark themes. +If we hear reports from maintainers that we could change something in this theme that would make their documentation look better, and if this change is sustainable for us, then we should do so. + +We store our PyData-specific SCSS in two relevant files, both in the ``src/pydata_sphinx_theme/assets/styles/`` folder: + +- ``extensions/_execution.scss`` - styles for Sphinx libraries that execute and insert code into the documentation. For example, nbsphinx, Jupyter Sphinx, and the Matplotlib ``plot`` directive. Most PyData support should go here via generic improvements that all packages benefit from. +- ``extensions/_pydata.scss`` - styles for specific libraries in the PyData ecosystem. In general we should try to keep this minimal because it is mostly special-casing single library quirks. diff --git a/docs/community/topics/warnings.md b/docs/community/topics/warnings.rst similarity index 53% rename from docs/community/topics/warnings.md rename to docs/community/topics/warnings.rst index 89588a16f..158bf4de0 100644 --- a/docs/community/topics/warnings.md +++ b/docs/community/topics/warnings.rst @@ -1,15 +1,16 @@ -# Expected build warnings +Expected build warnings +======================= In our CI workflow, we use a script to check for any warnings raised by Sphinx to assert that the only warnings are _expected_ ones. The list of expected warnings can be found in :code:`tests/warning_list.txt`. To add a new entry, copy/paste the warning message (the message beginning with :code:`WARNING:`) to the bottom of the file. For example if you get: -```console -Unexpected warning: C:\hostedtoolcache\windows\Python\3.9.13\x64\lib\site-packages\pandas\core\frame.py:docstring of pandas.core.frame.DataFrame.groupby:42: WARNING: undefined label: 'groupby.transform' -``` +.. code-block:: console + + Unexpected warning: C:\hostedtoolcache\windows\Python\3.9.13\x64\lib\site-packages\pandas\core\frame.py:docstring of pandas.core.frame.DataFrame.groupby:42: WARNING: undefined label: 'groupby.transform' Add the following to the txt file: -``` -WARNING: undefined label: 'groupby.transform' -``` +.. code-block:: + + WARNING: undefined label: 'groupby.transform' diff --git a/docs/conf.py b/docs/conf.py index e8d564a63..b0e279ec9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,6 +56,9 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] +# substitutions that will be available at global level +rst_prolog = ".. |rtd| replace: `Read the Docs `__" + # -- Sitemap ----------------------------------------------------------------- # ReadTheDocs has its own way of generating sitemaps, etc. @@ -71,7 +74,6 @@ # This allows us to use ::: to denote directives, useful for admonitions myst_enable_extensions = ["colon_fence", "linkify", "substitution"] myst_heading_anchors = 2 -myst_substitutions = {"rtd": "[Read the Docs](https://readthedocs.org/)"} # -- Internationalization ---------------------------------------------------- diff --git a/docs/examples/blog/post1.md b/docs/examples/blog/post1.md deleted file mode 100644 index 110733a55..000000000 --- a/docs/examples/blog/post1.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -blogpost: true -date: Jan 01, 2022 -author: pydata -location: World -category: Manual -tags: one, two, three -language: English ---- - -# Post one with a long-ish title we can use to compare - -Here's some text for post 1! - -## Post 1 section - -Some more text for post 1's section diff --git a/docs/examples/blog/post1.rst b/docs/examples/blog/post1.rst new file mode 100644 index 000000000..91c0df841 --- /dev/null +++ b/docs/examples/blog/post1.rst @@ -0,0 +1,17 @@ +:blogpost: true +:date: Jan 01, 2022 +:author: pydata +:location: World +:category: Manual +:tags: one, two, three +:language: English + +Post one with a long-ish title we can use to compare +==================================================== + +Here's some text for post 1! + +Post 1 section +-------------- + +Some more text for post 1's section diff --git a/docs/examples/blog/post2.md b/docs/examples/blog/post2.md deleted file mode 100644 index 2bff1a667..000000000 --- a/docs/examples/blog/post2.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -blogpost: true -date: Jan 02, 2022 -author: jupyter -location: World -category: Manual -tags: one, two, three, four, five, six -language: English ---- - -# Post title 2 with a longer title to compare in the UI - -Here's some text for post 2! - -## Post 2 section - -Some more text for post 2's section diff --git a/docs/examples/blog/post2.rst b/docs/examples/blog/post2.rst new file mode 100644 index 000000000..d0cbf062d --- /dev/null +++ b/docs/examples/blog/post2.rst @@ -0,0 +1,17 @@ +:blogpost: true +:date: Jan 02, 2022 +:author: jupyter +:location: World +:category: Manual +:tags: one, two, three, four, five, six +:language: English + +Post title 2 with a longer title to compare in the UI +===================================================== + +Here's some text for post 2! + +Post 2 section +-------------- + +Some more text for post 2's section diff --git a/docs/examples/blog/post3.md b/docs/examples/blog/post3.md deleted file mode 100644 index b80f3e50a..000000000 --- a/docs/examples/blog/post3.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -blogpost: true -date: Jan 03, 2022 -author: jupyter -location: World -category: Manual -tags: one, two, three, four, five, six, seven, eight, nine -language: English ---- - -# Post three with a long-ish title we can use to compare - -Here's some text for post 3! - -## Post 3 section - -Some more text for post 3's section diff --git a/docs/examples/blog/post3.rst b/docs/examples/blog/post3.rst new file mode 100644 index 000000000..e01e65987 --- /dev/null +++ b/docs/examples/blog/post3.rst @@ -0,0 +1,17 @@ +:blogpost: true +:date: Jan 03, 2022 +:author: jupyter +:location: World +:category: Manual +:tags: one, two, three, four, five, six, seven, eight, nine +:language: English + +Post three with a long-ish title we can use to compare +====================================================== + +Here's some text for post 3! + +Post 3 section +-------------- + +Some more text for post 3's section diff --git a/docs/examples/gallery.md b/docs/examples/gallery.md deleted file mode 100644 index 888b6d416..000000000 --- a/docs/examples/gallery.md +++ /dev/null @@ -1,48 +0,0 @@ -# Gallery of sites using this theme - -This is a gallery of documentation sites built with `pydata-sphinx-theme`. If you'd like -to add your documentation to this list, add an entry (in alphabetical order) to the list -at the end of [this page](https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/examples/gallery.md) -and open a Pull Request to add it. - -## Featured projects - -These projects are our earliest adopters and/or present some interesting customization. -Check their repositories for more information. - -```{gallery-grid} ../_static/gallery.yaml -:grid-columns: "1 1 2 2" -``` - -## Other projects using this theme - -Here are some other projects using `pydata-sphinx-theme` for their documentation. -Thanks for your support! - -```{gallery-grid} -:grid-columns: "1 2 3 4" -:class-card: "downstream-project-links" - -- title: Binder - link: https://mybinder.readthedocs.io/en/latest/index.html -- title: Brightway - link: https://docs.brightway.dev/en/latest/ -- title: cashocs - link: https://cashocs.readthedocs.io/en/stable/ -- title: CuPy - link: https://docs.cupy.dev/en/stable/index.html -- title: Fairlearn - link: https://fairlearn.org/main/about/ -- title: Feature-engine - link: https://feature-engine.readthedocs.io/ -- title: idtracker.ai - link: https://idtracker.ai/ -- title: MegEngine - link: https://www.megengine.org.cn/doc/stable/en/index.html -- title: PyVista - link: https://docs.pyvista.org -- title: Pastas - link: https://pastas.readthedocs.io/ -- title: DecentralChain - link: https://docs.decentralchain.io/en/master/ -``` diff --git a/docs/examples/gallery.rst b/docs/examples/gallery.rst new file mode 100644 index 000000000..b8ce0f780 --- /dev/null +++ b/docs/examples/gallery.rst @@ -0,0 +1,49 @@ +Gallery of sites using this theme +================================= + +This is a gallery of documentation sites built with ``pydata-sphinx-theme``. If you'd like +to add your documentation to this list, add an entry (in alphabetical order) to the list +at the end of `this page `__ +and open a Pull Request to add it. + +Featured projects +----------------- + +These projects are our earliest adopters and/or present some interesting customization. +Check their repositories for more information. + +.. gallery-grid:: ../_static/gallery.yaml + :grid-columns: "1 1 2 2" + +Other projects using this theme +------------------------------- + +Here are some other projects using ``pydata-sphinx-theme`` for their documentation. +Thanks for your support! + +.. gallery-grid:: + :grid-columns: "1 2 3 4" + :class-card: "downstream-project-links" + + - title: Binder + link: https://mybinder.readthedocs.io/en/latest/index.html + - title: Brightway + link: https://docs.brightway.dev/en/latest/ + - title: cashocs + link: https://cashocs.readthedocs.io/en/stable/ + - title: CuPy + link: https://docs.cupy.dev/en/stable/index.html + - title: Fairlearn + link: https://fairlearn.org/main/about/ + - title: Feature-engine + link: https://feature-engine.readthedocs.io/ + - title: idtracker.ai + link: https://idtracker.ai/ + - title: MegEngine + link: https://www.megengine.org.cn/doc/stable/en/index.html + - title: PyVista + link: https://docs.pyvista.org + - title: Pastas + link: https://pastas.readthedocs.io/ + - title: DecentralChain + link: https://docs.decentralchain.io/en/master/ diff --git a/docs/examples/no-sidebar.md b/docs/examples/no-sidebar.rst similarity index 70% rename from docs/examples/no-sidebar.md rename to docs/examples/no-sidebar.rst index 487fb5a17..f97135091 100644 --- a/docs/examples/no-sidebar.md +++ b/docs/examples/no-sidebar.rst @@ -1,11 +1,12 @@ -# Test of no sidebar +Test of no sidebar +================== This page shows off what the documentation looks like when you explicitly tell Sphinx not to include any sidebars via the following configuration: -```python -html_sidebars = { - "path/to/page": [], -} -``` +.. code-block:: python + + html_sidebars = { + "path/to/page": [], + } The primary sidebar should be entirely gone, and the main content should expand slightly to make up the extra space. diff --git a/docs/examples/persistent-search-field.md b/docs/examples/persistent-search-field.rst similarity index 75% rename from docs/examples/persistent-search-field.md rename to docs/examples/persistent-search-field.rst index cbae68012..4ea7aa7e3 100644 --- a/docs/examples/persistent-search-field.md +++ b/docs/examples/persistent-search-field.rst @@ -1,3 +1,4 @@ -# Test of persistent search field +Test of persistent search field +=============================== There should also be a persistent (non-hidden) search field in the primary sidebar of this page, and if you use the keyboard shortcut it should focus the persistent field, not overlay the hidden one. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 0e5562f93..000000000 --- a/docs/index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -myst: - html_meta: - "description lang=en": | - Top-level documentation for pydata-sphinx theme, with links to the rest - of the site.. -html_theme.sidebar_secondary.remove: true ---- - -# The PyData Sphinx Theme - -A clean, Bootstrap-based Sphinx theme by and for [the PyData community](https://pydata.org). - -```{gallery-grid} -:grid-columns: 1 2 2 3 - -- header: "{fab}`bootstrap;pst-color-primary` Built with Bootstrap" - content: "Use Bootstrap classes and functionality in your documentation." -- header: "{fas}`bolt;pst-color-primary` Responsive Design" - content: "Site sections will change behavior and size at different screen sizes." -- header: "{fas}`circle-half-stroke;pst-color-primary` Light / Dark theme" - content: "Users can toggle between light and dark themes interactively." -- header: "{fas}`palette;pst-color-primary` Customizable UI and themes" - content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design](user_guide/web-components)." -- header: "{fab}`python;pst-color-primary` Supports PyData and Jupyter" - content: "CSS and UI support for Jupyter extensions and PyData execution outputs." - link: "examples/pydata.html" -- header: "{fas}`lightbulb;pst-color-primary` Example Gallery" - content: "See our gallery of projects that use this theme." - link: "examples/gallery.html" -``` - -```{seealso} -If you are looking for a Sphinx theme that puts all of its sub-pages in the sidebar, the [Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/) has a similar look and feel, and [Furo](https://pradyunsg.me/furo/quickstart/) is another excellent choice. You can also see [the Sphinx Themes Gallery](https://sphinx-themes.org) for more ideas. -``` - -## User Guide - -Information about using, configuration, and customizing this theme. - -```{toctree} -:maxdepth: 2 - -user_guide/index -``` - -## Community and contribution guide - -Information about the community behind this theme and how you can contribute. - -```{toctree} -:maxdepth: 2 - -community/index -``` - -## Examples - -Several example pages to demonstrate the functionality of this theme when used alongside other Sphinx extensions. - -```{toctree} -:maxdepth: 2 - -examples/index -``` - -```{toctree} -:hidden: - -Changelog -``` - -## API - -The content of the exposed `pydata_sphinx_theme` API. - -```{toctree} -:maxdepth: 2 - -API -``` diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..1716ffc98 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,74 @@ +:html_theme.sidebar_secondary.remove: true + +The PyData Sphinx Theme +======================= + +A clean, Bootstrap-based Sphinx theme by and for `the PyData community `__. + +.. gallery-grid:: + :grid-columns: 1 2 2 3 + + - header: "{fab}`bootstrap;pst-color-primary` Built with Bootstrap" + content: "Use Bootstrap classes and functionality in your documentation." + - header: "{fas}`bolt;pst-color-primary` Responsive Design" + content: "Site sections will change behavior and size at different screen sizes." + - header: "{fas}`circle-half-stroke;pst-color-primary` Light / Dark theme" + content: "Users can toggle between light and dark themes interactively." + - header: "{fas}`palette;pst-color-primary` Customizable UI and themes" + content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design](user_guide/web-components)." + - header: "{fab}`python;pst-color-primary` Supports PyData and Jupyter" + content: "CSS and UI support for Jupyter extensions and PyData execution outputs." + link: "examples/pydata.html" + - header: "{fas}`lightbulb;pst-color-primary` Example Gallery" + content: "See our gallery of projects that use this theme." + link: "examples/gallery.html" + + +.. seealso:: + + If you are looking for a Sphinx theme that puts all of its sub-pages in the sidebar, the `Sphinx Book Theme `__ has a similar look and feel, and `Furo `__ is another excellent choice. You can also see `the Sphinx Themes Gallery `__ for more ideas. + +User Guide +---------- + +Information about using, configuration, and customizing this theme. + +.. toctree:: + :maxdepth: 2 + + user_guide/index + +Community and contribution guide +-------------------------------- + +Information about the community behind this theme and how you can contribute. + +.. toctree:: + :maxdepth: 2 + + community/index + +Examples +-------- + +Several example pages to demonstrate the functionality of this theme when used alongside other Sphinx extensions. + +.. toctree:: + :maxdepth: 2 + + examples/index + +.. toctree:: + :hidden: + + Changelog + +API +--- + +The content of the exposed `pydata_sphinx_theme` API. + +.. toctree:: + :maxdepth: 2 + + API diff --git a/docs/user_guide/ablog.md b/docs/user_guide/ablog.md deleted file mode 100644 index 19797b8e5..000000000 --- a/docs/user_guide/ablog.md +++ /dev/null @@ -1,30 +0,0 @@ -# Blogs with `ABlog` - -The [ABlog extension](https://ablog.readthedocs.io/) allows you to tag pages as **blog posts** and additionally include them in landing pages for your blog. -It also has several sidebar templates to show off collections of your posts. - -:::{admonition} Minimum version ABlog v0.11.0 -Make sure you have `ABlog>=0.11.0rc2` in your dependencies. -::: - -This theme has styling support for ABlog and demonstrates some of its functionality here. - -## Example blog - -Click below to go to the blog - -```{button-link} ../examples/blog/index.html -:color: primary -Go to the blog -``` - -## Example post list - -```{postlist} -:list-style: circle -:category: Manual -:date: "%Y-%m-%d" -:format: "{title} - {date}" -:excerpts: -:sort: -``` diff --git a/docs/user_guide/ablog.rst b/docs/user_guide/ablog.rst new file mode 100644 index 000000000..5b899cf4b --- /dev/null +++ b/docs/user_guide/ablog.rst @@ -0,0 +1,32 @@ +Blogs with ``ABlog`` +==================== + +The `ABlog extension `__ allows you to tag pages as **blog posts** and additionally include them in landing pages for your blog. +It also has several sidebar templates to show off collections of your posts. + +.. admonition:: Minimum version ABlog v0.11.0 + + Make sure you have `ABlog>=0.11.0rc2` in your dependencies. + +This theme has styling support for ABlog and demonstrates some of its functionality here. + +Example blog +------------ + +Click below to go to the blog + +.. button-link:: ../examples/blog/index.html + :color: primary + + Go to the blog + +Example post list +----------------- + +.. postlist:: + :list-style: circle + :category: Manual + :date: "%Y-%m-%d" + :format: "{title} - {date}" + :excerpts: + :sort: diff --git a/docs/user_guide/accessibility.md b/docs/user_guide/accessibility.md deleted file mode 100644 index 13cf9b1ed..000000000 --- a/docs/user_guide/accessibility.md +++ /dev/null @@ -1,142 +0,0 @@ -# Accessibility - -Creating and publishing content that does not exclude disabled users is a complex and iterative task. - -While there is no one-size-fits-all solution to maintaining accessible content, -the PyData Sphinx Theme and this documentation site use some techniques to avoid common content shortcomings. - -:::{note} -Issues and pull requests to identify or fix accessibility issues on this theme or site are heartily welcomed! -::: - -## What We've Done - -### Metadata - -Several of our documentation pages contain metadata (i.e., `.. meta::` directives -in reStructuredText) giving summaries of the page contents. If you notice a -page that lacks metadata, please open a pull request to add it! - -### Colors - -- Our default code highlighting styles are `a11y-high-contrast-light` and - `a11y-high-contrast-dark` from https://github.com/Quansight-Labs/accessible-pygments. - These styles are designed to meet WCAG 2 AA or AAA contrast requirements. - If you don't like the look of our default code highlighting styles, there are several more - to choose from at https://github.com/Quansight-Labs/accessible-pygments. -- We recently revisited the PyData Sphinx theme color palette to ensure that - the colors we use meet WCAG 2 AA or AAA contrast requirements. -- We also re-defined our `primary` and `secondary` colors to be more accessible and distinct from semantic colors used - to denote success, warning, info, and danger contexts or information. -- We simplified the color palette and removed some colors that were problematic in meeting WCAG 2 AA or AAA contrast requirements - and for certain types of colorblindness. -- We have improved how we assign text colors to interactive elements such as buttons and dropdowns to ensure that they meet - WCAG 2 AA or AAA contrast requirements. - -## What You Can Do - -### Site configuration - -The following sections include recommendations for settings in the `conf.py` file that can positively impact the -accessibility of content generated by this theme and Sphinx in general. - -### Natural Language - -If not using a more robust [internationalization approach](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html), -specifying at least the baseline natural language will help assistive technology -identify if the content is in a language the reader understands. - -:::{hint} -In your `conf.py` file, [specifying the language your docs are written in](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language) will propagate to the top-level `HTML` tag. - -```python - language = "en" -``` - -::: - -### Add a Site Map - -Site maps, usually served from a file called `sitemap.xml` are a broadly-employed -approach to telling programs like search engines and assistive technologies where -different content appears on a website. - -If using a service like [ReadTheDocs](https://readthedocs.com), these files -will be created for you _automatically_, but for some other approaches below, -it's handy to generate a `sitemap.xml` locally or in CI with a tool like -[sphinx-sitemap](https://pypi.org/project/sphinx-sitemap/). - -:::{hint} - -For a simple site (no extra languages or versions), ensure `sphinx-sitemap` -is installed in your documentation environment, and modify your `conf.py`: - -```python - extensions += ["sphinx_sitemap"] - - html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/") - sitemap_locales = [None] - sitemap_url_scheme = "{link}" -``` - -::: - -### Logo best practices - -If you use both light and dark themes, it's best to provide a logo that works well in both or to provide an alternative for the dark theme. -If you have a logo, you can add alt-text to it by adding the following to your -`conf.py`: - -```python - "logo": { - "text": "PyData Theme", - "image_dark": "_static/logo-dark.svg", - "alt_text": "PyData Theme home", - }, -``` - -Note the use of "home" in the alt text to indicate that the logo is also a link to the home page. - -### In the Browser - -Several in-browser tools exist for interactively debugging the accessibility -of a single page at a time and can be useful during the content development cycle. - -### Built-in tools - -Most major browsers, including [Firefox](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector) -and [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference), -have accessibility tools built-in as part of their web developer tools. -These tools can help to quickly identify accessibility issues and often include links to standards. - -#### tota11y - -[tota11y](https://khan.github.io/tota11y/#Installation) is an open source -"bookmarklet" which modifies the currently-loaded page in place and highlights -several accessibility issues. - -#### WAVE - -[WAVE](https://wave.webaim.org/extension/) is a proprietary (but _gratis_) -browser extension which can highlight multiple issues. - -:::{warning} -Note that automated testing and extensions such as the ones mentioned above will at best catch 30-40% of accessibility issues. -They are not a replacement for manual testing and having a perfect score on any of these tools does not mean that -the site can be used by disabled users but instead signals that it follows some accessibility best practices. -::: - -### In Continuous Integration - -Several automated tools are available for assessing _glaring_ accessibility -issues across some pages at once, usually with many configurable options. - -#### Lighthouse - -[Lighthouse](https://developers.google.com/web/tools/lighthouse) provides an automated assessment of basic accessibility issues in addition to search engine -automation, page performance, and other best practices. - -:::{hint} -Specifically, [foo-software/lighthouse-check-action](https://github.com/foo-software/lighthouse-check-action) -is run on selected pages from the generated documentation site. -::: diff --git a/docs/user_guide/accessibility.rst b/docs/user_guide/accessibility.rst new file mode 100644 index 000000000..01b2aa587 --- /dev/null +++ b/docs/user_guide/accessibility.rst @@ -0,0 +1,154 @@ +Accessibility +============= + +Creating and publishing content that does not exclude disabled users is a complex and iterative task. + +While there is no one-size-fits-all solution to maintaining accessible content, +the PyData Sphinx Theme and this documentation site use some techniques to avoid common content shortcomings. + +.. note:: + + Issues and pull requests to identify or fix accessibility issues on this theme or site are heartily welcomed! + +What We've Done +--------------- + +Metadata +^^^^^^^^ + +Several of our documentation pages contain metadata (i.e., ``.. meta::`` directives +in reStructuredText) giving summaries of the page contents. If you notice a +page that lacks metadata, please open a pull request to add it! + +Colors +^^^^^^ + +- Our default code highlighting styles are ``a11y-high-contrast-light`` and + ``a11y-high-contrast-dark`` from https://github.com/Quansight-Labs/accessible-pygments. + These styles are designed to meet WCAG 2 AA or AAA contrast requirements. + If you don't like the look of our default code highlighting styles, there are several more + to choose from at https://github.com/Quansight-Labs/accessible-pygments. +- We recently revisited the PyData Sphinx theme color palette to ensure that + the colors we use meet WCAG 2 AA or AAA contrast requirements. +- We also re-defined our ``primary`` and ``secondary`` colors to be more accessible and distinct from semantic colors used + to denote success, warning, info, and danger contexts or information. +- We simplified the color palette and removed some colors that were problematic in meeting WCAG 2 AA or AAA contrast requirements + and for certain types of colorblindness. +- We have improved how we assign text colors to interactive elements such as buttons and dropdowns to ensure that they meet + WCAG 2 AA or AAA contrast requirements. + +What You Can Do +--------------- + +Site configuration +^^^^^^^^^^^^^^^^^^ + +The following sections include recommendations for settings in the ``conf.py`` file that can positively impact the +accessibility of content generated by this theme and Sphinx in general. + +Natural Language +^^^^^^^^^^^^^^^^ + +If not using a more robust `internationalization approach `__, +specifying at least the baseline natural language will help assistive technology +identify if the content is in a language the reader understands. + +.. hint:: + + In your ``conf.py`` file, `specifying the language your docs are written in `__ will propagate to the top-level ``HTML`` tag. + + .. code-block:: python + + language = "en" + +Add a Site Map +^^^^^^^^^^^^^^ + +Site maps, usually served from a file called ``sitemap.xml`` are a broadly-employed +approach to telling programs like search engines and assistive technologies where +different content appears on a website. + +If using a service like |rdt|, these files +will be created for you _automatically_, but for some other approaches below, +it's handy to generate a ``sitemap.xml`` locally or in CI with a tool like +`sphinx-sitemap `__. + +.. hint:: + + For a simple site (no extra languages or versions), ensure ``sphinx-sitemap`` + is installed in your documentation environment, and modify your ``conf.py``: + + .. code-block:: python + + extensions += ["sphinx_sitemap"] + + html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/") + sitemap_locales = [None] + sitemap_url_scheme = "{link}" + +Logo best practices +^^^^^^^^^^^^^^^^^^^ + +If you use both light and dark themes, it's best to provide a logo that works well in both or to provide an alternative for the dark theme. +If you have a logo, you can add alt-text to it by adding the following to your +``conf.py``: + +.. code-block:: python + + "logo": { + "text": "PyData Theme", + "image_dark": "_static/logo-dark.svg", + "alt_text": "PyData Theme home", + }, + +Note the use of "home" in the alt text to indicate that the logo is also a link to the home page. + +In the Browser +^^^^^^^^^^^^^^ + +Several in-browser tools exist for interactively debugging the accessibility +of a single page at a time and can be useful during the content development cycle. + +Built-in tools +^^^^^^^^^^^^^^ + +Most major browsers, including `Firefox `__ +and `Chrome `__, +have accessibility tools built-in as part of their web developer tools. +These tools can help to quickly identify accessibility issues and often include links to standards. + +tota11y +""""""" + +`tota11y `__ is an open source +"bookmarklet" which modifies the currently-loaded page in place and highlights +several accessibility issues. + +WAVE +"""" + +`WAVE `__ is a proprietary (but _gratis_) +browser extension which can highlight multiple issues. + +.. warning:: + + Note that automated testing and extensions such as the ones mentioned above will at best catch 30-40% of accessibility issues. + They are not a replacement for manual testing and having a perfect score on any of these tools does not mean that + the site can be used by disabled users but instead signals that it follows some accessibility best practices. + +In Continuous Integration +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Several automated tools are available for assessing _glaring_ accessibility +issues across some pages at once, usually with many configurable options. + +Lighthouse +"""""""""" + +`Lighthouse `__ provides an automated assessment of basic accessibility issues in addition to search engine +automation, page performance, and other best practices. + +.. hint:: + + Specifically, [foo-software/lighthouse-check-action](https://github.com/foo-software/lighthouse-check-action) + is run on selected pages from the generated documentation site. diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md deleted file mode 100644 index 14a9401e9..000000000 --- a/docs/user_guide/index.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -myst: - html_meta: - "description lang=en": | - Documentation for users who wish to build sphinx sites with - pydata-sphinx-theme. ---- - -# User Guide - -You can configure the behavior, look, and feel of the theme in many ways. -The remaining pages in the user guide cover various ways of doing so. - -```{danger} -This theme is still under active development, and we make no promises -about the stability of any specific HTML structure, CSS variables, etc. -Make these customizations at your own risk, and pin versions if you're -worried about breaking changes! -``` - -There are a number of options for configuring your site's look and feel. -All configuration options are passed with the `html_theme_options` variable in your `conf.py` file. -This is a dictionary with `key: val` pairs that you can configure in various ways. - -```{toctree} -:caption: Get started - -install -layout -``` - -```{toctree} -:caption: Navigation and links - -navigation -page-toc -header-links -source-buttons -indices -``` - -```{toctree} -:maxdepth: 2 -:caption: User Interface - -announcements -version-dropdown -search -keyboard-shortcuts -i18n -``` - -```{toctree} -:caption: Content and features -theme-elements -ablog -web-components -extending -``` - -```{toctree} -:caption: Theming and Style - -branding -styling -fonts -light-dark -``` - -```{toctree} -:caption: Miscellaneous - -accessibility -analytics -static_assets -performance -readthedocs -``` diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst new file mode 100644 index 000000000..c79354a3b --- /dev/null +++ b/docs/user_guide/index.rst @@ -0,0 +1,64 @@ +User Guide +========== + +You can configure the behavior, look, and feel of the theme in many ways. +The remaining pages in the user guide cover various ways of doing so. + +.. danger:: + + This theme is still under active development, and we make no promises about the stability of any specific HTML structure, CSS variables, etc. + Make these customizations at your own risk, and pin versions if you're worried about breaking changes! + +There are a number of options for configuring your site's look and feel. +All configuration options are passed with the ``html_theme_options`` variable in your ``conf.py`` file. +This is a dictionary with ``key: val`` pairs that you can configure in various ways. + +.. toctree:: + :caption: Get started + + install + layout + +.. toctree:: + :caption: Navigation and links + + navigation + page-toc + header-links + source-buttons + indices + +.. toctree:: + :maxdepth: 2 + :caption: User Interface + + announcements + version-dropdown + search + keyboard-shortcuts + i18n + +.. toctree:: + :caption: Content and features + + theme-elements + ablog + web-components + extending + +.. toctree:: + :caption: Theming and Style + + branding + styling + fonts + light-dark + +.. toctree:: + :caption: Miscellaneous + + accessibility + analytics + static_assets + performance + readthedocs diff --git a/docs/user_guide/keyboard-shortcuts.md b/docs/user_guide/keyboard-shortcuts.md deleted file mode 100644 index 42bfeb93e..000000000 --- a/docs/user_guide/keyboard-shortcuts.md +++ /dev/null @@ -1,5 +0,0 @@ -# Keyboard shortcuts - -## Trigger the search bar - -You can trigger the search bar pop-up with {kbd}`Ctrl`/{kbd}`⌘` + {kbd}`K`. diff --git a/docs/user_guide/keyboard-shortcuts.rst b/docs/user_guide/keyboard-shortcuts.rst new file mode 100644 index 000000000..ca6a8f9c0 --- /dev/null +++ b/docs/user_guide/keyboard-shortcuts.rst @@ -0,0 +1,7 @@ +Keyboard shortcuts +================== + +Trigger the search bar +---------------------- + +You can trigger the search bar pop-up with :kbd:`Ctrl`/:kbd:`⌘` + :kbd:`K`. diff --git a/docs/user_guide/readthedocs.md b/docs/user_guide/readthedocs.md deleted file mode 100644 index 147afa017..000000000 --- a/docs/user_guide/readthedocs.md +++ /dev/null @@ -1,30 +0,0 @@ -# Read the Docs functionality - -This theme comes with support for {{ rtd }}, a popular service for hosting documentation in the scientific Python community. - -## Version switcher - -Projects hosted on {{ rtd }} can use the {{ rtd }} supplied version switcher instead of the [version switcher that this theme provides](version-dropdown.rst). -Its presence will be automatically detected by this theme, and placed in the `rtd-footer-container` node inside the primary sidebar. - -```{warning} -The {{ rtd }} version switcher will be hidden any time the primary sidebar is hidden (see [this section](layout-sidebar-primary) for discussion of when the primary sidebar might get hidden automatically and how to hide it purposely). -We intend to make {{ rtd }} switcher placement more flexible; you can track progress toward that in [this issue](https://github.com/pydata/pydata-sphinx-theme/issues/705). -``` - -## Add ethical advertisements to your sidebar - -If you're hosting your documentation on ReadTheDocs, you should consider -adding an explicit placement for their **ethical advertisements**. These are -non-tracking advertisements from ethical companies, and they help ReadTheDocs -sustain themselves and their free service. - -Ethical advertisements are added to your sidebar by default. To ensure they are -there if you manually update your sidebar, ensure that the `sidebar-ethical-ads.html` -template is added to your list. For example: - -```python -html_sidebars = { - "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"] -} -``` diff --git a/docs/user_guide/readthedocs.rst b/docs/user_guide/readthedocs.rst new file mode 100644 index 000000000..d461ec3e0 --- /dev/null +++ b/docs/user_guide/readthedocs.rst @@ -0,0 +1,33 @@ +Read the Docs functionality +=========================== + +This theme comes with support for |rtd|, a popular service for hosting documentation in the scientific Python community. + +Version switcher +---------------- + +Projects hosted on |rtd| can use the |rtd| supplied version switcher instead of the _`version switcher that this theme provides `. +Its presence will be automatically detected by this theme, and placed in the `rtd-footer-container` node inside the primary sidebar. + +.. warning:: + + The |rtd| version switcher will be hidden any time the primary sidebar is hidden (see _`this section ` for discussion of when the primary sidebar might get hidden automatically and how to hide it purposely). + We intend to make |rtd| switcher placement more flexible; you can track progress toward that in [this issue](https://github.com/pydata/pydata-sphinx-theme/issues/705). + +Add ethical advertisements to your sidebar +------------------------------------------ + +If you're hosting your documentation on ReadTheDocs, you should consider +adding an explicit placement for their **ethical advertisements**. These are +non-tracking advertisements from ethical companies, and they help ReadTheDocs +sustain themselves and their free service. + +Ethical advertisements are added to your sidebar by default. To ensure they are +there if you manually update your sidebar, ensure that the ``sidebar-ethical-ads.html`` +template is added to your list. For example: + +.. code-block:: python + + html_sidebars = { + "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"] + } diff --git a/docs/user_guide/static_assets.md b/docs/user_guide/static_assets.md deleted file mode 100644 index 1f3d308c9..000000000 --- a/docs/user_guide/static_assets.md +++ /dev/null @@ -1,157 +0,0 @@ -# Add custom CSS and JS assets - -If you'd like to modify this theme or sections on the page, you'll need to add custom CSS or JavaScript to your theme. -Since this is a common operation we cover a few ways to do this here. - -````{admonition} Sample site structure -In all examples below, assume we have a site structure like this: - -``` -mysphinxsite/ -├── _static -│   ├── mycss.css -│   └── myjs.js -└── conf.py -``` -```` - -## First: define your `html_static_path` - -Any folders that are listed in `html_static_path` will be treated as containing static assets for your build. -All files within these folders will be copied to your build's `_static` folder at build time. -For example, with an HTML builder, files will be copied to `_build/html/_static`. - -These files are _flattened_ when they are copied, so any folder hierarchies will be lost. - -Listing folders with your static assets must be done before any of the methods described below. -When you define asset names in the methods described below, they generally assume paths that are _relative to this `_static` output folder_. - -## Define a list of assets in `conf.py` - -The simplest way to add JS and CSS assets is to use [`html_css_files`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files) and [`html_js_files`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_js_files) in your `conf.py` file. -Each can be a list of paths, _relative to your `html_static_path`_. -They will be added to the end of the `` of your site. - -For example: - -```{code-block} python ---- -caption: '`conf.py`' ---- - -html_static_path = ["_static"] -html_css_files = ["mycss.css"] -html_js_files = ["myjs.js"] -``` - -This will cause each to be linked in your ``. - -## Add assets to your setup function - -Additionally, you may add assets manually, to do so, use the `app` object in [the Sphinx `setup()` function](https://www.sphinx-doc.org/en/master/extdev/appapi.html#extension-setup). -The `app` object has two relevant methods here: - -[**`app.add_css_file`**](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file) allows you to add CSS files directly. - -[**`app.add_js_file`**](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file) allows you to add JS files directly. - -Both of them expect you to add files **relative to the `html_static_path`**. - -In addition, `app.add_js_file` allows you to add _raw JavaScript_ in addition to linking files (see example below). -For example: - -```{code-block} python ---- -caption: '`conf.py`' ---- - -html_static_path = ["_static"] - -def setup(app): - app.add_css_file("mycss.css") - app.add_js_file("myjs.js") - - # Add raw JavaScript - rawjs = """ - let a = "foo"; - console.log(a + " bar") - """ - app.add_js_file(None, body=rawjs) -``` - -## Use an event to add it to specific pages - -If you'd like to use logic to only add a script to certain pages or to trigger different behavior depending on the page, use [a Sphinx event hook](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events). -This involves defining a function that runs when a particular event is emitted in the Sphinx build, and using [`app.connect()`](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.connect) to connect it to your build. - -The event you'll likely want to use is [`html-page-context`](https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-html-page-context). -This is triggered just before the HTML for an _individual page_ is created. -If you run `app.add_js_file` or `app.add_css_file`, it will _only be added for that page_. - -For example: - -```{code-block} python ---- -caption: '`conf.py`' ---- -html_static_path = ["_static"] - -def add_my_files(app, pagename, templatename, context, doctree): - if pagename == "dontaddonthispage": - return - - app.add_css_file("mycss.css") - -def setup(app): - app.connect("html-page-context", add_my_files) -``` - -## Add it directly to the page content - -Finally, you can add CSS or JS directly to a page's content. -If you're using reStructuredText you can use the `.. raw::` directive; if you're using MyST Markdown you can simply include the HTML content in-line with your Markdown-formatted content. - -``````{tab-set} -`````{tab-item} rST -````{code-block} rst -:caption: some_page_in_my_site.rst -My title -======== - -Some text - -.. raw:: html - - - -A bigger title --------------- - -Some other text -```` -````` -`````{tab-item} Markdown -````{code-block} md -:caption: some_page_in_my_site.md -# My title - -Some text - - - -## A bigger title - -Some other text -```` -````` -`````` diff --git a/docs/user_guide/static_assets.rst b/docs/user_guide/static_assets.rst new file mode 100644 index 000000000..9ef83749a --- /dev/null +++ b/docs/user_guide/static_assets.rst @@ -0,0 +1,155 @@ +Add custom CSS and JS assets +============================ + +If you'd like to modify this theme or sections on the page, you'll need to add custom CSS or JavaScript to your theme. +Since this is a common operation we cover a few ways to do this here. + +.. admonition:: Sample site structure + + In all examples below, assume we have a site structure like this: + + .. code-block:: + + mysphinxsite/ + ├── _static + │   ├── mycss.css + │   └── myjs.js + └── conf.py + +First: define your ``html_static_path`` +--------------------------------------- + +Any folders that are listed in ``html_static_path`` will be treated as containing static assets for your build. +All files within these folders will be copied to your build's ``_static`` folder at build time. +For example, with an HTML builder, files will be copied to ``_build/html/_static``. + +These files are _flattened_ when they are copied, so any folder hierarchies will be lost. + +Listing folders with your static assets must be done before any of the methods described below. +When you define asset names in the methods described below, they generally assume paths that are *relative to this ``_static`` output folder*. + +Define a list of assets in ``conf.py`` +-------------------------------------- + +The simplest way to add JS and CSS assets is to use `html_css_files `__ and `html_js_files `__ in your ``conf.py`` file. +Each can be a list of paths, *relative to your ``html_static_path``*. +They will be added to the end of the ```` of your site. + +For example: + +.. code-block:: python + :caption: '``conf.py``' + + html_static_path = ["_static"] + html_css_files = ["mycss.css"] + html_js_files = ["myjs.js"] + +This will cause each to be linked in your ````. + +Add assets to your setup function +--------------------------------- + +Additionally, you may add assets manually, to do so, use the ``app`` object in `the Sphinx ``setup()`` function `__. +The ``app`` object has two relevant methods here: + +- `app.add_css_file `__ allows you to add CSS files directly. +- `app.add_js_file `__ allows you to add JS files directly. + +Both of them expect you to add files **relative to the ``html_static_path``**. + +In addition, ``app.add_js_file`` allows you to add *raw JavaScript* in addition to linking files (see example below). +For example: + +.. code-block:: python + :caption: ``conf.py`` + + html_static_path = ["_static"] + + def setup(app): + app.add_css_file("mycss.css") + app.add_js_file("myjs.js") + + # Add raw JavaScript + rawjs = """ + let a = "foo"; + console.log(a + " bar") + """ + app.add_js_file(None, body=rawjs) + +Use an event to add it to specific pages +---------------------------------------- + +If you'd like to use logic to only add a script to certain pages or to trigger different behavior depending on the page, use `a Sphinx event hook `__. +This involves defining a function that runs when a particular event is emitted in the Sphinx build, and using `app.connect() `__ to connect it to your build. + +The event you'll likely want to use is `html-page-context `__. +This is triggered just before the HTML for an *individual page* is created. +If you run ``app.add_js_file`` or ``app.add_css_file``, it will *only be added for that page*. + +For example: + +.. code-block:: python + :caption: ``conf.py`` + + html_static_path = ["_static"] + + def add_my_files(app, pagename, templatename, context, doctree): + if pagename == "dontaddonthispage": + return + + app.add_css_file("mycss.css") + + def setup(app): + app.connect("html-page-context", add_my_files) + +Add it directly to the page content +----------------------------------- + +Finally, you can add CSS or JS directly to a page's content. +If you're using reStructuredText you can use the ``.. raw::`` directive; if you're using MyST Markdown you can simply include the HTML content in-line with your Markdown-formatted content. + +.. tab-set:: + + .. tab-item:: rST + + .. code-block:: rst + :caption: some_page_in_my_site.rst + + My title + ======== + + Some text + + .. raw:: html + + + + A bigger title + -------------- + + Some other text + + .. tab-item:: Markdown + + .. code-block:: md + :caption: some_page_in_my_site.md + + # My title + + Some text + + + + ## A bigger title + + Some other text diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md deleted file mode 100644 index 06e905224..000000000 --- a/docs/user_guide/theme-elements.md +++ /dev/null @@ -1,257 +0,0 @@ -# Theme-specific elements - -There are a few elements that are unique or particularly important to this theme. -Some of these are triggered with configuration or Markdown syntax that is unique to the theme, and we cover them below. - -```{contents} Page contents -:local: -``` - -## Mathematics - -Most Sphinx sites support math, but it is particularly important for scientific computing, so we illustrate support here as well. - -Here is an inline equation: {math}`X_{0:5} = (X_0, X_1, X_2, X_3, X_4)` and {math}`another` and {math}`x^2 x^3 x^4` another. And here's one to test vertical height {math}`\frac{\partial^2 f}{\partial \phi^2}`. -Here is a block-level equation: - -```{math} -:label: My label - -\nabla^2 f = -\frac{1}{r^2} \frac{\partial}{\partial r} -\left( r^2 \frac{\partial f}{\partial r} \right) + -\frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} -\left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + -\frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} -``` - -And here is a really long equation with a label! - -```{math} -:label: My label 2 - -\nabla^2 f = -\frac{1}{r^2} \frac{\partial}{\partial r} -\left( r^2 \frac{\partial f}{\partial r} \right) + -\frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} -\left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + -\frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} -\nabla^2 f = -\frac{1}{r^2} \frac{\partial}{\partial r} -\left( r^2 \frac{\partial f}{\partial r} \right) + -\frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} -\left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + -\frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} -``` - -You can add a link to equations like the one above {eq}`My label` and {eq}`My label 2`. - -## Code blocks - -Code block styling is inspired by [GitHub's code block style](https://primer.style/css/components/markdown) and also has support for Code Block captions/titles. -See [the Sphinx documentation on code blocks](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) for more information. - -```python -print("A regular code block") -print("A regular code block") -print("A regular code block") -``` - -You can also provide captions with code blocks, which will be displayed right above the code. -For example, the following code: - -``````{tab-set} -`````{tab-item} rST -````rst -.. code-block:: python - :caption: python.py - - print("A code block with a caption.") -```` -````` -`````{tab-item} Markdown -````md -```{code-block} python -:caption: python.py - -print("A code block with a caption.") -``` -```` -````` -`````` - -results in: - -```{code-block} python -:caption: python.py - -print("A code block with a caption.") -``` - -You can also display line numbers. -For example, the following code: - -``````{tab-set} -`````{tab-item} rST -````rst -.. code-block:: python - :caption: python.py - :linenos: - - print("A code block with a caption and line numbers.") - print("A code block with a caption and line numbers.") - print("A code block with a caption and line numbers.") -```` -````` -`````{tab-item} Markdown -````md -```{code-block} python -:caption: python.py -:linenos: - -print("A code block with a caption and line numbers.") -print("A code block with a caption and line numbers.") -print("A code block with a caption and line numbers.") -``` -```` -````` -`````` - -results in: - -```{code-block} python -:caption: python.py -:linenos: - -print("A code block with a caption and line numbers.") -print("A code block with a caption and line numbers.") -print("A code block with a caption and line numbers.") -``` - -## Inline code - -When used directly, the `code` role just displays the text without syntax highlighting, as a literal. As mentioned in the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#inline-code-highlighting) you can also enable syntax highlighting by defining a custom role. It will then use the same highlighter as in the `code-block` directive. - -``````{tab-set} -`````{tab-item} rst -````rst -.. role:: python(code) - :language: python - -In Python you can :python:`import sphinx`. -```` -````` -`````{tab-item} markdown -````md -```{role} python(code) -:language: python -``` - -In Python you can {python}`import sphinx`. -```` -````` -`````` - -```{role} python(code) -:language: python -``` - -In Python you can {python}`import sphinx`. - -## Code execution - -This theme has support for Jupyter execution libraries so that you can programmatically update your documentation with each build. -For examples, see [](../examples/pydata.ipynb). - -## Admonition sidebars - -```{admonition} A sidebar admonition! -:class: sidebar note -I was made with the `{admonition}` directive and a `sidebar` class. -``` - -```{sidebar} Sidebar title -I was made with the `{sidebar}` directive. -``` - -This theme supports a shorthand way of making **admonitions behave like sidebars**. -This can be a helpful way of highlighting content without interrupting the vertical flow as much. - -For example, on the right are an "admonition sidebar" and a traditional Sphinx sidebar. - -To make an admonition behave like a sidebar, add the `sidebar` class to its list of classes. -The admonition sidebar in this section was created with the following Markdown: - -``````{tab-set} -`````{tab-item} rST -````rst -.. admonition:: A sidebar admonition! - :class: sidebar note - - Some sidebar content. -```` -````` -`````{tab-item} Markdown -````md -```{admonition} A sidebar admonition! -:class: sidebar note -Some sidebar content. -``` -```` -````` -`````` - -## Footnotes - -Here's a numeric footnote[^1], another one (preceded by a space) [^2], a named footnote[^named], and a symbolic one[^*]. -All will end up as numbers in the rendered HTML, but in the source they look like `[^1]`, `[^2]`, `[^named]` and `[^*]`. - -[^1]: Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. -[^2]: Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. -[^named]: Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. -[^*]: Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. - -## Link shortening for git repository services - -Many projects have links back to their issues / PRs hosted on platforms like **GitHub** or **GitLab**. -Instead of displaying these as raw links, this theme does some lightweight formatting for these platforms specifically. - -In **reStructuredText**, URLs are automatically converted to links, so this works automatically. - -In **MyST Markdown**, by default, you must define a standard Markdown link and duplicate the URL in the link text. -You may skip the need to manually define the link text by [activating the MyST Linkify extension](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#linkify). - -For example: - -- **reStructuredText** - - - `https://github.com/pydata/pydata-sphinx-theme/pull/1012` - - https://github.com/pydata/pydata-sphinx-theme/pull/1012 - -- **MyST Markdown (default)** - - - `[https://github.com/pydata/pydata-sphinx-theme/pull/1012](https://github.com/pydata/pydata-sphinx-theme/pull/1012)` - - [https://github.com/pydata/pydata-sphinx-theme/pull/1012](https://github.com/pydata/pydata-sphinx-theme/pull/1012) - -- **MyST Markdown with [MyST Linkify](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#linkify)** - - `https://github.com/pydata/pydata-sphinx-theme/pull/1012` - - https://github.com/pydata/pydata-sphinx-theme/pull/1012 - -There are a variety of link targets supported, here's a table for reference: - -**GitHub** - -- `https://github.com`: https://github.com -- `https://github.com/pydata`: https://github.com/pydata -- `https://github.com/pydata/pydata-sphinx-theme`: https://github.com/pydata/pydata-sphinx-theme -- `https://github.com/pydata/pydata-sphinx-theme/pull/1012`: https://github.com/pydata/pydata-sphinx-theme/pull/1012 -- `https://github.com/orgs/pydata/projects/2`: https://github.com/orgs/pydata/projects/2 - -**GitLab** - -- `https://gitlab.com`: https://gitlab.com -- `https://gitlab.com/gitlab-org`: https://gitlab.com/gitlab-org -- `https://gitlab.com/gitlab-org/gitlab`: https://gitlab.com/gitlab-org/gitlab -- `https://gitlab.com/gitlab-org/gitlab/-/issues/375583`: https://gitlab.com/gitlab-org/gitlab/-/issues/375583 - -Links provided with a text body won't be changed. diff --git a/docs/user_guide/theme-elements.rst b/docs/user_guide/theme-elements.rst new file mode 100644 index 000000000..b9466944e --- /dev/null +++ b/docs/user_guide/theme-elements.rst @@ -0,0 +1,271 @@ +Theme-specific elements +======================= + +There are a few elements that are unique or particularly important to this theme. +Some of these are triggered with configuration or Markdown syntax that is unique to the theme, and we cover them below. + +.. contents:: Page contents + :local: + +Mathematics +----------- + +Most Sphinx sites support math, but it is particularly important for scientific computing, so we illustrate support here as well. + +Here is an inline equation: :math:`X_{0:5} = (X_0, X_1, X_2, X_3, X_4)` and :math:`another` and :math:`x^2 x^3 x^4` another. And here's one to test vertical height :math:`\frac{\partial^2 f}{\partial \phi^2}`. +Here is a block-level equation: + +.. math:: + :label: My label + + \nabla^2 f = + \frac{1}{r^2} \frac{\partial}{\partial r} + \left( r^2 \frac{\partial f}{\partial r} \right) + + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} + \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} + +And here is a really long equation with a label! + +.. math:: + :label: My label 2 + + \nabla^2 f = + \frac{1}{r^2} \frac{\partial}{\partial r} + \left( r^2 \frac{\partial f}{\partial r} \right) + + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} + \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} + \nabla^2 f = + \frac{1}{r^2} \frac{\partial}{\partial r} + \left( r^2 \frac{\partial f}{\partial r} \right) + + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} + \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} + +You can add a link to equations like the one above :eq:`My label` and :eq:`My label 2`. + +Code blocks +----------- + +Code block styling is inspired by `GitHub's code block style `__ and also has support for Code Block captions/titles. +See `the Sphinx documentation on code blocks `__ for more information. + +.. code-block:: python + + print("A regular code block") + print("A regular code block") + print("A regular code block") + +You can also provide captions with code blocks, which will be displayed right above the code. +For example, the following code: + +.. tab-set:: + + .. tab-item:: rST + + .. code-block:: rst + + .. code-block:: python + :caption: python.py + + print("A code block with a caption.") + + .. tab-item:: Markdown + + .. code-block:: md + + ```{code-block} python + :caption: python.py + + print("A code block with a caption.") + ``` + +results in: + +.. code-block:: python + :caption: python.py + + print("A code block with a caption.") + +You can also display line numbers. +For example, the following code: + +.. tab-set:: + + .. tab-item:: rST + + .. code-block:: rst + + .. code-block:: python + :caption: python.py + :linenos: + + print("A code block with a caption and line numbers.") + print("A code block with a caption and line numbers.") + print("A code block with a caption and line numbers.") + + .. tab-item:: Markdown + + .. code-block:: md + + ```{code-block} python + :caption: python.py + :linenos: + + print("A code block with a caption and line numbers.") + print("A code block with a caption and line numbers.") + print("A code block with a caption and line numbers.") + ``` + +results in: + +.. code-block:: python + :caption: python.py + :linenos: + + print("A code block with a caption and line numbers.") + print("A code block with a caption and line numbers.") + print("A code block with a caption and line numbers.") + +Inline code +----------- + +When used directly, the ``code`` role just displays the text without syntax highlighting, as a literal. As mentioned in the `Sphinx documentation `__ you can also enable syntax highlighting by defining a custom role. It will then use the same highlighter as in the ``code-block`` directive. + +.. tab-set:: + + .. tab-item:: rst + + .. code-block:: rst + + .. role:: python(code) + :language: python + + In Python you can :python:`import sphinx`. + + .. tab-item:: markdown + + .. code-block:: md + + ```{role} python(code) + :language: python + ``` + + In Python you can {python}`import sphinx`. + +.. role:: python(code) + :language: python + +In Python you can :python:`import sphinx`. + +Code execution +-------------- + +This theme has support for Jupyter execution libraries so that you can programmatically update your documentation with each build. +For examples, see _`../examples/pydata.ipynb`. + +Admonition sidebars +------------------- + +.. admonition:: A sidebar admonition! + :class: sidebar note + + I was made with the ``.. admonition`` directive and a ``sidebar`` class. + +.. sidebar:: Sidebar title + + I was made with the ``.. sidebar`` directive. + +This theme supports a shorthand way of making **admonitions behave like sidebars**. +This can be a helpful way of highlighting content without interrupting the vertical flow as much. + +For example, on the right are an "admonition sidebar" and a traditional Sphinx sidebar. + +To make an admonition behave like a sidebar, add the ``sidebar`` class to its list of classes. +The admonition sidebar in this section was created with the following Markdown: + +.. tab-set:: + + .. tab-item:: rST + + .. code-block:: rst + + .. admonition:: A sidebar admonition! + :class: sidebar note + + Some sidebar content. + + .. tab-item:: Markdown + + .. code-block:: md + + ```{admonition} A sidebar admonition! + :class: sidebar note + Some sidebar content. + ``` + +Footnotes +--------- + +Here's a numeric footnote[1], another one (preceded by a space) [2], a named footnote[named], and a symbolic one[*]. +All will end up as numbers in the rendered HTML, but in the source they look like ``[1]``, ``[2]``, ``[named]`` and ``[*]``. + +.. [1] Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. + +.. [2] Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. + +.. [named] Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. + +.. [*] Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. Foo bar foo bar. + +Link shortening for git repository services +------------------------------------------- + +Many projects have links back to their issues / PRs hosted on platforms like **GitHub** or **GitLab**. +Instead of displaying these as raw links, this theme does some lightweight formatting for these platforms specifically. + +In **reStructuredText**, URLs are automatically converted to links, so this works automatically. + +In **MyST Markdown**, by default, you must define a standard Markdown link and duplicate the URL in the link text. +You may skip the need to manually define the link text by `activating the MyST Linkify extension `__. + +For example: + +.. tab-set:: + + .. tab-item:: reStructuredText + + - ``https://github.com/pydata/pydata-sphinx-theme/pull/1012`` + - https://github.com/pydata/pydata-sphinx-theme/pull/1012 + + .. tab-item:: **MyST Markdown (default)** + + - ``[https://github.com/pydata/pydata-sphinx-theme/pull/1012](https://github.com/pydata/pydata-sphinx-theme/pull/1012)`` + - `https://github.com/pydata/pydata-sphinx-theme/pull/1012 `__ + + .. tab-item:: **MyST Markdown (MyST Linkify) + + - ``https://github.com/pydata/pydata-sphinx-theme/pull/1012`` + - https://github.com/pydata/pydata-sphinx-theme/pull/1012 + +There are a variety of link targets supported, here's a table for reference: + +.. tab-set:: + + .. tab-item:: **GitHub** + + - ``https://github.com``: https://github.com + - ``https://github.com/pydata``: https://github.com/pydata + - ``https://github.com/pydata/pydata-sphinx-theme``: https://github.com/pydata/pydata-sphinx-theme + - ``https://github.com/pydata/pydata-sphinx-theme/pull/1012``: https://github.com/pydata/pydata-sphinx-theme/pull/1012 + - ``https://github.com/orgs/pydata/projects/2``: https://github.com/orgs/pydata/projects/2 + + .. tab-item:: **GitLab** + + - ``https://gitlab.com``: https://gitlab.com + - ``https://gitlab.com/gitlab-org``: https://gitlab.com/gitlab-org + - ``https://gitlab.com/gitlab-org/gitlab``: https://gitlab.com/gitlab-org/gitlab + - ``https://gitlab.com/gitlab-org/gitlab/-/issues/375583``: https://gitlab.com/gitlab-org/gitlab/-/issues/375583 + +Links provided with a text body won't be changed. diff --git a/src/pydata_sphinx_theme/assets/scripts/bootstrap.js b/src/pydata_sphinx_theme/assets/scripts/bootstrap.js index ec34c0d4e..66845be66 100644 --- a/src/pydata_sphinx_theme/assets/scripts/bootstrap.js +++ b/src/pydata_sphinx_theme/assets/scripts/bootstrap.js @@ -14,7 +14,7 @@ import "../styles/bootstrap.scss"; */ function TriggerTooltip() { var tooltipTriggerList = [].slice.call( - document.querySelectorAll('[data-bs-toggle="tooltip"]') + document.querySelectorAll('[data-bs-toggle="tooltip"]'), ); tooltipTriggerList.map(function (tooltipTriggerEl) { return new Tooltip(tooltipTriggerEl, { delay: { show: 500, hide: 100 } }); diff --git a/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js b/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js index 99ddbeab0..943423b48 100644 --- a/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js +++ b/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js @@ -142,7 +142,7 @@ function scrollToActive() { // Inspired on source of revealjs.com let storedScrollTop = parseInt( sessionStorage.getItem("sidebar-scroll-top"), - 10 + 10, ); if (!isNaN(storedScrollTop)) { @@ -194,7 +194,7 @@ var findSearchInput = () => { } else { // must be at least one persistent form, use the first persistent one form = document.querySelector( - "div:not(.search-button__search-container) > form.bd-search" + "div:not(.search-button__search-container) > form.bd-search", ); } return form.querySelector("input"); @@ -245,7 +245,7 @@ var addEventListenerForSearchKeyboard = () => { toggleSearchField(); } }, - true + true, ); }; @@ -273,7 +273,7 @@ var changeSearchShortcutKey = () => { let shortcuts = document.querySelectorAll(".search-button__kbd-shortcut"); if (isMac(window.navigator)) { shortcuts.forEach( - (f) => (f.querySelector("kbd.kbd-shortcut__modifier").innerText = "⌘") + (f) => (f.querySelector("kbd.kbd-shortcut__modifier").innerText = "⌘"), ); } }; @@ -391,7 +391,7 @@ function populateVersionSwitcher(data, versionSwitcherBtns) { const anchor = document.createElement("a"); anchor.setAttribute( "class", - "dropdown-item list-group-item list-group-item-action py-1" + "dropdown-item list-group-item list-group-item-action py-1", ); anchor.setAttribute("href", `${entry.url}${currentFilePath}`); anchor.setAttribute("role", "option"); @@ -451,7 +451,7 @@ function showVersionWarningBanner(data) { if (preferredEntries.length !== 1) { const howMany = preferredEntries.length == 0 ? "No" : "Multiple"; console.log( - `[PST] ${howMany} versions marked "preferred" found in versions JSON, ignoring.` + `[PST] ${howMany} versions marked "preferred" found in versions JSON, ignoring.`, ); return; } @@ -536,17 +536,17 @@ function initRTDObserver() { // fetch the JSON version data (only once), then use it to populate the version // switcher and maybe show the version warning bar var versionSwitcherBtns = document.querySelectorAll( - ".version-switcher__button" + ".version-switcher__button", ); const hasSwitcherMenu = versionSwitcherBtns.length > 0; const hasVersionsJSON = DOCUMENTATION_OPTIONS.hasOwnProperty( - "theme_switcher_json_url" + "theme_switcher_json_url", ); const wantsWarningBanner = DOCUMENTATION_OPTIONS.show_version_warning_banner; if (hasVersionsJSON && (hasSwitcherMenu || wantsWarningBanner)) { const data = await fetchVersionSwitcherJSON( - DOCUMENTATION_OPTIONS.theme_switcher_json_url + DOCUMENTATION_OPTIONS.theme_switcher_json_url, ); populateVersionSwitcher(data, versionSwitcherBtns); if (wantsWarningBanner) { diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss index d74bbbb9f..9aa9873fa 100644 --- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss +++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss @@ -6,7 +6,8 @@ * A consistent box shadow style we apply across elements. */ @mixin box-shadow() { - box-shadow: 0 0.2rem 0.5rem var(--pst-color-shadow), + box-shadow: + 0 0.2rem 0.5rem var(--pst-color-shadow), 0 0 0.0625rem var(--pst-color-shadow) !important; } diff --git a/src/pydata_sphinx_theme/assets/styles/content/_api.scss b/src/pydata_sphinx_theme/assets/styles/content/_api.scss index 22c228438..aff8a3ecc 100644 --- a/src/pydata_sphinx_theme/assets/styles/content/_api.scss +++ b/src/pydata_sphinx_theme/assets/styles/content/_api.scss @@ -117,7 +117,9 @@ span.highlighted { // the API selector // from https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/content/_api.sass#L6) -dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) { +dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not( + .simple + ) { dd { margin-left: 2rem; diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-toggle.scss b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-toggle.scss index 95657b53b..bb9962ecc 100644 --- a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-toggle.scss +++ b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-toggle.scss @@ -67,7 +67,8 @@ input { width: 75%; flex-grow: 0.75; max-width: 350px; - transition: visibility $animation-time ease-out, + transition: + visibility $animation-time ease-out, margin $animation-time ease-out; visibility: hidden;