Release 2.0.0rc3 (#1535)

* Fix #1522: fix attribute error if css is str

* Revert "Fix #1522: fix attribute error if css is str"

This reverts commit b22a77f35a.

* Use `css_tag` only for standard CSS files from Sphinx

... and keep using the custom `link` HTML tag for CSS files included via the
HTML theme option `extra_css_files`.

* Normalize template variables

---------

Co-authored-by: Manuel Kaufmann <humitos@gmail.com>
Co-authored-by: Anthony Johnson <aj@ohess.org>

.readthedocs.yml

@@ -1,7 +1,11 @@
 version: 2
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
 python:
-  version: 3.8
   install:
     - requirements: docs/requirements.txt
     - method: pip

docs/changelog.rst

@@ -4,13 +4,18 @@ Changelog
 
 .. seealso:: :ref:`howto_upgrade`
 
-.. |theme_version| replace:: 2.0.0rc1
+.. |theme_version| replace:: 2.0.0rc3
 
 .. _release-2.0.0:
 
-2.0.0rc1
+2.0.0rc3
 ========
 
+Added
+-----
+
+* Support for docutils ``<=0.20``
+
 Deprecations
 ------------
 

docs/demo/api.rst

@@ -7,19 +7,11 @@ API documentation and generated content
 :mod:`test_py_module`
 =====================
 
-.. only:: python3
+.. automodule:: test_py_module.test
+    :members:
+    :private-members:
+    :special-members:
 
-    .. automodule:: test_py_module.test
-        :members:
-        :private-members:
-        :special-members:
-
-.. only:: python2
-
-    .. automodule:: test_py_module.test_py27
-        :members:
-        :private-members:
-        :special-members:
 
 C++ API
 =======
@@ -153,18 +145,8 @@ Sphinx Extensions
 sphinx.ext.autosummary
 ----------------------
 
-.. only:: python3
+.. autosummary::
 
-    .. autosummary::
-
-        test_py_module.test.add_numbers
-        test_py_module.test.subtract_numbers
-        test_py_module.test.Foo
-
-.. only:: python2
-
-    .. autosummary::
-
-        test_py_module.test_py27.add_numbers
-        test_py_module.test_py27.subtract_numbers
-        test_py_module.test_py27.Foo
+    test_py_module.test.add_numbers
+    test_py_module.test.subtract_numbers
+    test_py_module.test.Foo

docs/demo/test_py_module/test_py27.py

@@ -1,152 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-This module will overwrite test.py for Python 2.7 builds.
-Type signatures cause autodoc to break in Python 2.7 documentation builds, so they are removed here.
-
-Test Module for sphinx_rtd_theme."""
-
-
-class Foo:
-
-    """Docstring for class Foo.
-
-    This text tests for the formatting of docstrings generated from output
-    ``sphinx.ext.autodoc``. Which contain reST, but sphinx nests it in the
-    ``<dl>``, and ``<dt>`` tags. Also, ``<tt>`` is used for class, method names
-    and etc, but those will *always* have the ``.descname`` or
-    ``.descclassname`` class.
-
-    Term
-        It is also possible to include definitions inside docstrings.
-        They should be styled as a normal definition list.
-
-    :Field List:
-        It is also possible to include definitions inside docstrings.
-        They should be styled as a normal definition list.
-
-    .. [1] A footnote contains body elements, consistently indented by at
-       least 3 spaces.
-
-    .. [Citation] A citation contains body elements, consistently indented by at
-       least 3 spaces.
-
-    Normal ``<tt>`` (like the <tt> I just wrote here) needs to be shown with
-    the same style as anything else with ````this type of markup````.
-
-    It's common for programmers to give a code example inside of their
-    docstring::
-
-        from test_py_module import Foo
-
-        myclass = Foo()
-        myclass.dothismethod('with this argument')
-        myclass.flush()
-
-        print(myclass)
-
-
-    Here is a link to :py:meth:`capitalize`.
-    Here is a link to :py:meth:`__init__`.
-
-    """
-
-    #: Doc comment for class attribute Foo.bar.
-    #: It can have multiple lines.
-    bar = 1
-
-    flox = 1.5   #: Doc comment for Foo.flox. One line only.
-
-    baz = 2
-    """Docstring for class attribute Foo.baz."""
-
-    def __init__(self, qux, spam=False):
-        """Start the Foo.
-
-        :param qux: The first argument to initialize class.
-        :type qux: string
-        :param spam: Spam me yes or no...
-        :type spam: bool
-
-        """
-        #: Doc comment for instance attribute qux.
-        self.qux = 3
-
-        self.spam = 4
-        """Docstring for instance attribute spam."""
-
-    def add(self, val1, val2):
-        """Return the added values.
-
-        :param val1: First number to add.
-        :type val1: int
-        :param val2: Second number to add.
-        :type val2: int
-        :rtype: int
-
-        The parameters of this method are described in the parameter list.
-        """
-
-        return val1 + val2
-
-    def capitalize(self, myvalue):
-        """Return a string as uppercase.
-
-        :param myvalue: String to change
-        :type myvalue: string
-        :rtype: string
-
-        """
-
-        return myvalue.upper()
-
-    def another_function(self, a, b, **kwargs):
-        """
-        Here is another function.
-
-        :param a: The number of green hats you own.
-        :type a: int
-
-        :param b: The number of non-green hats you own.
-        :type b: int
-
-        :param kwargs: Additional keyword arguments. Each keyword parameter
-                       should specify the name of your favorite cuisine.
-                       The values should be floats, specifying the mean price
-                       of your favorite dish in that cooking style.
-        :type kwargs: float
-
-        :returns: A 2-tuple.  The first element is the mean price of all dishes
-                  across cuisines.  The second element is the total number of
-                  hats you own: :math:`a + b`.
-        :rtype: tuple
-
-        :raises ValueError: When ``a`` is not an integer.
-
-        .. versionadded:: 1.0
-            This was added in 1.0
-        .. versionchanged:: 2.0
-            This was changed in 2.0
-        .. deprecated:: 3.0
-            This is deprecated since 3.0
-        """
-        return sum(kwargs.values()) / len(kwargs), a + b
-
-
-def add_numbers(a, b):
-    """Add two numbers together
-
-    :param a: The first number
-    :param b: The second number
-
-    Here is some more text.
-    """
-    return a + b
-
-
-def subtract_numbers(a, b):
-    """Subtract two numbers
-
-    :param a: The first number
-    :param b: The second number
-    """
-    return a - b

docs/installing.rst

@@ -58,21 +58,3 @@ Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1.
     
     More information is available in Read the Docs' documentation on :doc:`rtd:guides/reproducible-builds`.
 
-
-Via Git or Download
--------------------
-
-.. warning::
-
-   Installing directly from the repository source is deprecated and is not
-   recommended. Static assets won't be included in the repository starting in
-   release :ref:`roadmap-release-3.0.0`.
-
-Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
-``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
-``conf.py`` file:
-
-.. code:: python
-
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = ["_themes", ]

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx_rtd_theme",
-  "version": "2.0.0rc1",
+  "version": "2.0.0rc3",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {

package.json

@@ -1,7 +1,7 @@
 {
   "name": "sphinx_rtd_theme",
   "main": "js/theme.js",
-  "version": "2.0.0rc1",
+  "version": "2.0.0rc3",
   "scripts": {
     "dev": "webpack-dev-server --open --config webpack.dev.js",
     "build": "webpack --config webpack.prod.js",

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.0.0rc1
+current_version = 2.0.0rc3
 commit = false
 tag = false
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)((?P<release>[a-z]+)(?P<dev>\d+))?
@@ -46,7 +46,7 @@ packages = sphinx_rtd_theme
 python_requires = >=3.6
 install_requires = 
 	sphinx >=5,<8
-	docutils <0.19
+	docutils <0.21
 	sphinxcontrib-jquery >=4,<5
 tests_require = 
 	pytest

setup.py

@@ -86,7 +86,7 @@ class TransifexCommand(distutils.cmd.Command):
 
 
 setup(
-    version='2.0.0rc1',
+    version='2.0.0rc3',
     cmdclass={
         'update_translations': UpdateTranslationsCommand,
         'transifex': TransifexCommand,

sphinx_rtd_theme/__init__.py

@@ -12,7 +12,7 @@ from sphinx.locale import _
 from sphinx.util.logging import getLogger
 
 
-__version__ = '2.0.0rc1'
+__version__ = '2.0.0rc3'
 __version_full__ = __version__
 
 logger = getLogger(__name__)

sphinx_rtd_theme/layout.html

@@ -14,7 +14,7 @@
 {%- set sphinx_version_info = (_ver_major, _ver_minor, -1) -%}
 
 <!DOCTYPE html>
-<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
+<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
 <head>
   <meta charset="utf-8" />
   {{- metatags }}
@@ -28,16 +28,13 @@
     <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
     <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
   {%- endif %}
-  {%- for css in css_files %}
-    {%- if css|attr("rel") %}
-      <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
-    {%- else %}
-      <link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
-    {%- endif %}
+  {%- for css_file in css_files %}
+    {{ css_tag(css_file) }}
   {%- endfor %}
 
-  {%- for cssfile in extra_css_files %}
-    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {# "extra_css_files" is a theme option and it's always a string #}
+  {%- for css_file in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
   {%- endfor -%}
 
   {#- FAVICON

tox.ini

@@ -25,6 +25,9 @@ deps =
     sphinx72: Sphinx>=7.2,<7.3
     sphinxlatest: Sphinx
     dev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
+allowlist_externals =
+    echo
 commands =
     pytest {posargs} tests/
     sphinx-build -b html -Dhtml4_writer=0 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html
+    echo "Open the following URL for visual testing: file://{envtmpdir}/html/demo/demo.html"