Remove upperbound on sphinx (#661)

* Remove upperbound on sphinx

* Explain that we don't test old releases against future releases of our dependencies

* Clarify Sphinx policy

Co-authored-by: Chris Holdgraf <[email protected]>
Co-authored-by: Chris Holdgraf <[email protected]>

Author: jarrodmillman

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)

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.

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
@@ -19,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:

pyproject.toml

@@ -18,7 +18,7 @@ readme = "README.md"
 
 requires-python = ">=3.7"
 dependencies = [
-  "sphinx>=4,<6",
+  "sphinx>=4",
   "beautifulsoup4",
   "docutils!=0.17.0",
   "packaging"