Merge pull request #21 from khancyr/update-1.3.0

Update to sphinx theme master 1.3.0

.circleci/config.yml

@@ -1,5 +1,8 @@
 version: 2.1
 
+orbs:
+  node: circleci/node@5.0.2
+
 commands:
   run-tox:
     description: "Run tox"
@@ -8,15 +11,17 @@ commands:
         type: string
       sphinx-version:
         type: string
-        default: "16,17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,latest"
+        default: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest"
     steps:
       - checkout
-      - run: pip install --user tox
+      - run: pip install --user tox~=3.27
       - run: tox -e "<<parameters.version>>-sphinx{<<parameters.sphinx-version>>}"
   run-build:
     description: "Ensure built assets are up to date"
     steps:
       - checkout
+      - node/install:
+          node-version: '14.20'
       - run: npm ci
       - run: npm run build
       - run:
@@ -41,6 +46,7 @@ jobs:
     steps:
       - run-tox:
           version: py27
+          sphinx-version: "17,18"
   py36:
     docker:
       - image: 'cimg/python:3.6'
@@ -59,18 +65,40 @@ jobs:
     steps:
       - run-tox:
           version: py38
+          sphinx-version: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,60,latest"
   py39:
     docker:
       - image: 'cimg/python:3.9'
     steps:
       - run-tox:
           version: py39
+          sphinx-version: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,60,latest"
+  py310:
+    docker:
+      - image: 'cimg/python:3.10'
+    steps:
+      - run-tox:
+          version: py310
+          sphinx-version: "42,43,44,45,50,51,52,53,60,latest"
+  py311:
+    docker:
+      - image: 'cimg/python:3.11'
+    steps:
+      - run-tox:
+          version: py311
+          sphinx-version: "53,60,latest"
 
 workflows:
   version: 2
   tests:
     jobs:
       - build
+      - py311:
+          requires:
+            - build
+      - py310:
+          requires:
+            - build
       - py39:
           requires:
             - build

.gitignore

@@ -21,6 +21,11 @@ sphinx_rtd_theme/static/fonts/Lato/
 sphinx_rtd_theme/static/fonts/RobotoSlab/
 .python-version
 .node-version
+.tool-versions
+.nvmrc
 sphinx_rtd_theme/static/js/html5shiv.min.js
 sphinx_rtd_theme/static/js/html5shiv-printshiv.min.js
-.nvmrc
+.direnv/
+.envrc
+# Used for dockerized builds
+.container_id

.tx/config

@@ -1,9 +1,10 @@
 [sphinx-rtd-theme.sphinx-rtd-theme]
 file_filter = sphinx_rtd_theme/locale/<lang>/LC_MESSAGES/sphinx.po
+minimum_perc = 60
 source_file = sphinx_rtd_theme/locale/en/LC_MESSAGES/sphinx.po
 source_lang = en
-minimum_perc = 60
 
 [main]
 host = https://www.transifex.com
 type = PO
+

Dockerfile

@@ -0,0 +1,60 @@
+# This implicitely includes Python 3.10
+FROM node:14-alpine
+
+# Do not use --update since that will also fetch the
+# latest node-current package
+# 'make' is needed for building documentation
+RUN apk add npm make py3-pip py3-wheel
+
+# Add an extra verification that we have the right node
+# because the above caused issues
+RUN node -v && node -v | grep -q v14 &&\
+    python3 --version && python3 --version | grep -q "3.10"
+
+RUN pip install pip --upgrade
+
+RUN mkdir -p /project/src/ &&\
+    mkdir -p /project/docs/build/ &&\
+    mkdir -p /project-minimal-copy/sphinx_rtd_theme &&\
+    touch /project-minimal-copy/sphinx_rtd_theme/__init__.py
+
+# This is the main working directory where node_modules
+# gets built. During runtime, it's mixed with directories
+# from an external environment through a bind mount
+WORKDIR /project
+
+# Copy files necessary to run "npm install" and save
+# installed packages in the docker image (makes the runtime
+# so much faster)
+COPY package.json /project/
+COPY bin/preinstall.js /project/bin/preinstall.js
+
+RUN cd /project
+
+# It matters that the node environment is installed into the same
+# folder, i.e. /project where we will run the environment from
+# TODO: We don't want to update package-lock.json here, we
+# should use npm ci instead
+RUN npm install --package-lock-only &&\
+    npm audit fix &&\
+    npm install
+
+# This is strictly speaking not necessary, just makes
+# running the container faster...
+# Install dependencies, then uninstall project itself
+COPY setup.py README.rst /project-minimal-copy/
+RUN cd /project-minimal-copy &&\
+    pip install ".[dev]" &&\
+    /usr/bin/yes | pip uninstall sphinx_rtd_theme
+
+
+# Copy in files that we need to run the project. These files
+# will not be mounted into the runtime from external environment
+# so we copy them during build.
+COPY webpack.common.js webpack.dev.js webpack.prod.js /project/
+
+# Copy in the entrypoint and we're done
+COPY docker-entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

Makefile

@@ -0,0 +1,19 @@
+SHELL := /bin/bash
+CWD := $(shell cd -P -- '$(shell dirname -- "$0")' && pwd -P)
+
+docker-images:
+	docker-compose build
+
+docker-npm-build:
+	rm -f .container_id
+	docker-compose run -d sphinx_rtd_theme build > .container_id
+	sleep 1s
+	docker container wait "$(shell cat .container_id)"
+	docker cp "$(shell cat .container_id):/project/sphinx_rtd_theme" .
+	docker cp "$(shell cat .container_id):/project/package-lock.json" .
+	@echo "Done building"
+
+docker-npm-dev:
+	docker-compose run sphinx_rtd_theme dev
+
+docker-build-all: docker-images docker-npm-build

docker-compose.yaml

@@ -0,0 +1,26 @@
+version: "3.2"
+services:
+
+  sphinx_rtd_theme:
+    build: .
+    volumes:
+      - type: "bind"
+        source: "./"
+        target: "/project-readonly"
+        read_only: true
+      - type: "volume"
+        target: "/project-readonly/sphinx_rtd_theme.egg-info"
+      - type: "bind"
+        source: "./src"
+        target: "/project/src"
+        read_only: true
+      - type: "bind"
+        source: "./docs"
+        target: "/project/docs"
+        read_only: false #todo: fix this
+      - type: "volume"
+        target: "/project/docs/_build"
+
+    network_mode: host
+    ports:
+      - "1919:1919"

docker-entrypoint.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+
+# Update latest Python dependencies in case they have changed
+# Notice that we are using the 'eager' strategy
+# This should only be relevant to development environments where
+# the theme is being used. For purposes of "production" or
+# building the sdist/wheel, installing dependencies should not
+# affect the outcome.
+cd /project-readonly
+pip install --upgrade --upgrade-strategy eager -e ".[dev]"
+
+# This helps a potential permission issue, but might be removed
+# pending some more investigation of docker host file system
+# permissions in the bind mount
+# npm cache clean --force
+# npm install
+
+cd /project
+
+# TODO: This is a bad approach, it copies from the image which
+# may be outdated to the current git tree
+cp -r /project-readonly/sphinx_rtd_theme .
+
+echo "Going to invoke: npm run $@"
+npm run $@

docs/changelog.rst

@@ -2,6 +2,147 @@
 Changelog
 *********
 
+.. seealso:: :ref:`howto_upgrade`
+
+.. |theme_version| replace:: 1.3.0
+
+.. _release-1.3.0:
+
+1.3.0
+=====
+
+Added
+-----
+
+* Relaxed requirements to include Sphinx release ``7.0``
+
+.. _release-1.2.2:
+
+1.2.2
+=====
+
+Fixes
+-----
+
+* Require `sphinxcontrib-jquery>=4,<5` (#1446)
+
+Added
+-----
+
+* Styling for `:menuselection:` (#1426)
+
+
+.. _release-1.2.1:
+
+1.2.1
+=====
+
+Fixes
+-----
+
+* Load jQuery correctly when using latest sphinxcontrib-jquery release (#1448)
+
+
+.. _release-1.2.0:
+
+1.2.0
+=====
+
+Dependency changes
+------------------
+
+* docutils 0.18 is supported. (#1381)
+* Sphinx 6 support added
+* Added ``sphinxcontrib-jquery`` as a dependency (#1385 #1421)
+* Python 3.11 is officially supported and tested. (#1395)
+* Python 3.4 and 3.5 are officially not supported (#1395)
+
+Changes
+-------
+
+* Automatically use ``sphinxcontrib-jquery`` in Sphinx 6+ (#1399)
+* Use new context vars ``logo_url``, ``favicon_url`` and ``root_doc`` when available (#1405)
+* Translations updated: French, Hungarian, Croatian
+* Translations added: Danish, Chinese (Taiwan)
+
+Note for users of Sphinx<4
+--------------------------
+
+If you cannot use a more recent Sphinx release,
+you should at least ensure you are using the most recent release for your major version.
+Currently, these are Sphinx `1.8.6` and `2.4.5`.
+Older releases may install unsupported versions of several dependencies, including Jinja2 and docutils.
+
+Known issues
+------------
+
+In some cases, jQuery is not loaded with Sphinx 6 on Read the Docs.
+Workaround: You need to add ``sphinx_rtd_theme`` to ``extensions`` in your ``conf.py``.
+See `readthedocs.org issue #9654`_ for updates.
+
+.. _readthedocs.org issue #9654: https://github.com/readthedocs/readthedocs.org/pull/9654
+
+
+.. _release-1.1.1:
+
+1.1.1
+=====
+
+Fixes
+-----
+
+* Fix wrapping bug on cross references (#1368)
+
+.. _release-1.1.0:
+
+1.1.0
+=====
+
+Dependency Changes
+------------------
+
+Many documentation projects depend on ``sphinx-rtd-theme`` without specifying a version of the theme (unpinned) while also depending on unpinned versions of Sphinx. The latest version of ``sphinx-rtd-theme`` ideally always supports the latest version of Sphinx, but this is now guaranteed.
+
+This release adds upper bounds to direct dependencies ``Sphinx`` and ``docutils`` which will safeguard from mixing with possibly incompatible future versions of Sphinx & docutils.
+
+* Sphinx versions supported: 1.6 to 5.2.x
+* ``Sphinx<6`` (#1332)
+* ``docutils<0.18`` (unchanged, but will be bumped in an upcoming release)
+
+
+Features
+--------
+
+* Nicer styles for <kbd> (#967)
+* New styling for breadcrumbs (#1073)
+
+
+Fixes
+-----
+
+* Suffixes in Sphinx version caused build errors (#1345)
+* Table cells with multiple paragraphs gets wrong formatting (#289)
+* Definition lists rendered wrongly in api docs (#1052)
+* Citation not styled properly (#1078)
+* Long URLs did not wrap (#1193)
+
+
+Minor Changes
+-------------
+
+* Sphinx 5.2 added to test matrix (#1348)
+* Python 3.10 added to test matrix (#1334)
+* Supplemental Docker setup for development (#1319)
+* Most of setup.py migrated to setup.cfg (#1116)
+* Jinja2 context variable ``sphinx_version_info`` is now ``(major, minor, -1)``, the patch component is always ``-1``. Reason: It's complicated. (#1345)
+
+
+Incompatible Changes
+--------------------
+
+There are no known incompatible changes in this release. Support for ``docutils`` versions 0.18 and 0.19 are scheduled for our next release.
+
+
 .. _release-1.0.0:
 
 1.0.0