From aeedc7c2855c05994a3c05855e4ca908285760c2 Mon Sep 17 00:00:00 2001 From: Jarrod Millman Date: Wed, 11 May 2022 11:04:15 -0700 Subject: [PATCH 1/3] Remove upperbound on sphinx --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 009361e36..e4fe49895 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,7 +18,7 @@ readme = "README.md" requires-python = ">=3.7" dependencies = [ - "sphinx>=3.5.4,<5", + "sphinx>=3.5.4", "beautifulsoup4", "docutils!=0.17.0", "packaging" From 525aa8f8559cf2b2606000bebf78567634faa115 Mon Sep 17 00:00:00 2001 From: Jarrod Millman Date: Mon, 16 May 2022 12:34:52 -0700 Subject: [PATCH 2/3] Explain that we don't test old releases against future releases of our dependencies --- docs/user_guide/install.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/user_guide/install.rst b/docs/user_guide/install.rst index b536dde13..225e600e9 100644 --- a/docs/user_guide/install.rst +++ b/docs/user_guide/install.rst @@ -2,6 +2,15 @@ Installation ************ +.. note:: + + Each pydata-sphinx-theme release has a minimum required Sphinx version, + which should be automatically handled by your package installer. + It is also tested against newer versions of Sphinx that were available + prior to that release of the pydata-sphinx-theme package. + If you run into issues when trying to use a more recent version of Sphinx, + please open an issue here: https://github.com/pydata/pydata-sphinx-theme/issues + The theme is available on PyPI and conda-forge, and can thus be installed with: .. code:: console From c707588c389e1197db0ad1df80b2cece24870cde Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 25 May 2022 18:03:36 +0200 Subject: [PATCH 3/3] Clarify Sphinx policy --- README.md | 77 ++++--------------------------------- docs/contribute/topics.md | 10 +++++ docs/user_guide/install.rst | 8 ++++ 3 files changed, 25 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index f197ba3ea..249aa8361 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,6 @@ A Bootstrap-based Sphinx theme from the PyData community. Demo site: https://pydata-sphinx-theme.readthedocs.io/en/latest/ -**Note**: This theme is originally being developed for the pandas docs (originally named "pandas-sphinx-theme"), -but since there is uptake in other projects, we are working on making this more -generic and more easily extensible to suit the needs of the different projects. - Sites that are using this theme: - Pandas: https://pandas.pydata.org/docs/ @@ -47,75 +43,16 @@ and use as follows: And that's it! -Well, in principle at least. In practice, there are might still be a few -pandas-specific things that are right now hard-coded in the theme. We also need -to work on better configurability and extensibility. Feedback and contributions -are very welcome! +> **Note** +> This theme may not work with the latest major versions of Sphinx, especially +> if they have only recently been released. Please give us a few months of +> time to work out any bugs and changes when new releases are made. +> See [our contributing documentation](docs/contribute/topics.md) for more information. -## Theme development +## Contribute to and develop the theme Contributions are very welcome! Installing the development version, building the demo docs and developing the css/js of the theme, etc, is explained in more detail in the contributing section of the documentation: -- [Contributing source files](docs/contributing.md) -- [Contributing rendered docs](https://pydata-sphinx-theme.readthedocs.io/en/latest/contributing.html) - -## How is this theme working? - -### The html layout - -The "layout" included in this theme is originally mainly targeted towards -documentation sites with many pages, and where putting all navigation in a -single sidebar can therefore get unwieldy. - -The current layout features 3 navigation elements: - -- A top navbar with top-level navigation -- A left sidebar with subsequent navigation up to single pages -- A right sidebar with a local "On this page" table of contents - -What is put where is determined by the sphinx "toctree" (and such depending on -the structure of your sphinx docs). The first level of the toctree is put in the -top navbar, and the second (and potentially) third level is put in the left -sidebar. - -It should certainly be possible to make the exact used levels of the sphinx -toctree configurable. - -### Implementation details - -A second aspect of the design of this theme is that we are trying to make good -use of Bootstrap features and use as much as possible actual (templated) html -and css to define the theme, instead of relying on sphinx to do custom -formatting. This should make the theming and layouts more flexible to customize. - -To this end, this package includes: - -- A [`BootstrapHTML5Translator`](./pydata_sphinx_theme/bootstrap_html_translator.py), - subclassing sphinx' translator, but overriding certain elements to generate - Bootstrap-compatible html. Currently, this includes: converting admonitions to - Bootstrap "alert" classes, and updating the classes used for html tables. -- A [sphinx event](./pydata_sphinx_theme/__init__.py) to add navigation - objects into the html context which is available in the html (jinja2) - templates. This allows to put the structure of the navigation elements in the - actual layout, instead of having to rely on the hard-coded formatting of - sphinx (this is inspired on the navigation objects of mkdocs: - https://www.mkdocs.org/user-guide/custom-themes/#nav). We would love to see - this added to sphinx itself (instead of needing a sphinx event), but for now - did not yet get any reaction from the sphinx developers. - -Those items also avoid writing javascript functions to "fix up" the html -generated by sphinx to make it suitable for theming. - -### What's the difference with bootstrap-sphinx-theme ? - -There is already a sphinx Bootstrap theme used by some project in the community: -https://github.com/ryan-roemer/sphinx-bootstrap-theme/ - -Currently, the main difference is that this theme is using Bootstrap 4 instead -of 3 and provides a different default layout. At some point, it would be good to -contribute changes to that package (or at least the parts that deal with -Bootstrap and sphinx that could be shared). - -The initial layout and css were inspired on the Bootstrap documentation site. +- [Contributing documentation](https://pydata-sphinx-theme.readthedocs.io/en/stable/contribute/index.html) diff --git a/docs/contribute/topics.md b/docs/contribute/topics.md index 4ebefdfe4..f5f3c9bcb 100644 --- a/docs/contribute/topics.md +++ b/docs/contribute/topics.md @@ -212,6 +212,16 @@ The output of the last command includes: - a short summary of the current state of the accessibility rules we are trying to maintain - local paths to JSON and HTML reports which contain all of the issues found +## Update support for new Sphinx versions + +This theme does not pin the upper version of Sphinx that it supports, but there may be changes that need to happen when Sphinx releases a new version. +As a general rule, we try to support new major Sphinx versions within 6 months of its release. + +Here's a list of things to check when Sphinx releases a new version: + +- [Look at the Sphinx Changelog](https://www.sphinx-doc.org/en/master/changes.html) and make sure there are no obvious breaking changes. +- [Look at the deprecated API changes](https://www.sphinx-doc.org/en/master/extdev/deprecated.html) and make sure there are no obvious breaking changes. + ## Update our kitchen sink documents The [kitchen sink reference](../demo/kitchen-sink/index.rst) is for demonstrating as much syntax and style for Sphinx builds as possible. diff --git a/docs/user_guide/install.rst b/docs/user_guide/install.rst index 225e600e9..2870e5cde 100644 --- a/docs/user_guide/install.rst +++ b/docs/user_guide/install.rst @@ -28,6 +28,14 @@ configuration option: html_theme = "pydata_sphinx_theme" +.. note:: + + This theme may not work with the latest major versions of Sphinx, especially + if they have only recently been released. Please give us a few months of + time to work out any bugs and changes when new releases are made. + +Development version +=================== If you want to track the development version of the theme, you can install it from the git repo: