diff options
author | Benjamin Bach <benjamin@overtag.dk> | 2022-08-19 16:50:16 +0300 |
---|---|---|
committer | Benjamin Bach <benjamin@overtag.dk> | 2022-08-19 16:50:16 +0300 |
commit | 0f76e9ba4a8ca5ef5d945eda4ea818b1acd94ea7 (patch) | |
tree | f5fa24004867d10ada343ef0c3a95f844799974d /docs | |
parent | 85123c47de9357828e391a4f6af743415eaab537 (diff) | |
parent | 4efbdbc8eb040ddfa5abb6afeba9eb73f9d8d2dd (diff) |
Merge branch 'master' of github.com:readthedocs/sphinx_rtd_theme into HEAD
Diffstat (limited to 'docs')
-rw-r--r-- | docs/changelog.rst | 151 | ||||
-rw-r--r-- | docs/contributing.rst | 7 | ||||
-rw-r--r-- | docs/development.rst | 180 | ||||
-rw-r--r-- | docs/index.rst | 54 | ||||
-rw-r--r-- | docs/installing.rst | 32 | ||||
-rw-r--r-- | docs/supported-browsers.csv | 5 |
6 files changed, 351 insertions, 78 deletions
diff --git a/docs/changelog.rst b/docs/changelog.rst index 9ef2299..87422ef 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -2,11 +2,15 @@ Changelog ********* -master -====== +Development version (|development_version|) +=========================================== -v1.0.0 -====== +.. |development_version| replace:: 1.0.1alpha1 + +.. _release-1.0.0: + +1.0.0 +===== Incompatible Changes -------------------- @@ -17,7 +21,42 @@ Incompatible Changes Deprecated ---------- -* Support for sphinx's html4 writer is deprecated and will be removed in version 2.0 (#1091) +* Support for Sphinx's HTML4 writer is deprecated and will be removed in version 2.0 (#1091) + +Features +-------- + +* Add support for Sphinx 4.x (#1123) +* Add support for Docutils 0.17 (#1185 and #1199) +* Fixed logo scaling on IE11 (#1183) +* Added support for logos as URLs (#1171) +* Align top and side navigation background colors on mobile (#1132) +* Added support for deep toc levels (#1089) +* Updated translations for Chinese, Dutch, Estonian, French, German, Italian, + Lithuanian, Persian, Polish, Portuguese, Russian, Spanish, Swedish, and + Turkish locales + +A number of accessibility features were added in this release: + +* Allow keyboard to toggle menu expansion (#1167) +* Allow keyboard to activate permalink (#1162) +* Show keyboard focus on buttons (#1161) +* Maintain aria-expanded along with .current in menu (#1151) +* Respect tab order for prev/next buttons (#1051) + +Fixes +----- + +* Updated Google analytics integration (#1129) +* Add classifier separation on Sphinx 2+ HTML4 writer (#1192) +* Added missing space char in footer (#1188) +* Fix navigation right padding on level2+ elements (#1068) +* Fix navigation expansion button sizes (#1067) +* Wrap inline literals (#1050) +* Fix aria labels (#1056) +* Don't toggle navigation terminal nodes (#1049) +* Fix ``<pre>`` overflow (#1220) +* Fix literal/ref style inside ``<dl>`` (#1088) Other Changes ------------- @@ -25,22 +64,12 @@ Other Changes * Update npm development dependencies (#1096) * Don't require npm to build from source (#1039) * Use regular toctree instead of toc for singlehtml builder (#507) -* Templates: Cleanup Whitespace (#1060) +* Cleanup whitespace in templates (#1060) -Fixes ------ +.. _release-0.5.2: -* Javascript: Add support for deep toc levels (#1089) -* Use Proper Sass Syntax (#1069) -* Nav: Fix right padding on level2+ (#1068) -* Fix Nav Buttons Size (#1067) -* Fix: wrap inline literals (#1050) -* Fix aria label (#1056) -* Respect tab order for prev/next buttons (#1051) -* Nav: Don't toggle terminal nodes (#1049) - -v0.5.2 -====== +0.5.2 +===== :Date: April 5, 2021 @@ -49,8 +78,10 @@ v0.5.2 * Depend on docutils < 0.17 (#1113) -v0.5.1 -====== +.. _release-0.5.1: + +0.5.1 +===== :Date: January 4, 2021 @@ -79,8 +110,10 @@ Other Changes * Make Copyright template match sphinx's basic (#933) * Packaging: include ``bin/preinstall.js`` (#1005) -v0.5.0 -====== +.. _release-0.5.0: + +0.5.0 +===== :Date: Jun 17, 2020 @@ -89,8 +122,10 @@ Fixes * Fix bullet list spacing to respect simple/complex list styles -v0.5.0rc2 -========= +.. _release-0.5.0rc2: + +0.5.0rc2 +======== :Date: June 5, 2020 @@ -102,8 +137,10 @@ Fixes * Fix several margin issues with lists, nested lists, and nested content * Add colon back to field lists -v0.5.0rc1 -========= +.. _release-0.5.0rc1: + +0.5.0rc1 +======== :Date: May 6, 2020 @@ -121,8 +158,10 @@ Other Changes * Moved build system from Grunt and friends to Webpack * Remove Modernizr, but keep html5shiv (#724, #525) -v0.4.3 -====== +.. _release-0.4.3: + +0.4.3 +===== :Date: Feb 12, 2019 @@ -141,8 +180,10 @@ Fixes Other Changes -------------- -v0.4.2 -====== +.. _release-0.4.2: + +0.4.2 +===== :Date: Oct 5, 2018 @@ -161,8 +202,8 @@ Other Changes * Upload signed packages to PyPI with twine (#651) * Do not enforce period at the end of copyright statement (666) -v0.4.1 -====== +0.4.1 +===== :Date: July 27, 2018 @@ -179,8 +220,8 @@ Other Changes * Add Sphinx as a dependency -v0.4.0 -====== +0.4.0 +===== This version made some changes to how JS and CSS were included when the theme is used on Read the Docs. @@ -202,8 +243,8 @@ Other Changes * Changed code and literals to use a native font stack (#612) * Fix small styling issues -v0.3.1 -====== +0.3.1 +===== Fixes ----- @@ -214,8 +255,8 @@ Fixes * Add open list spacing (#591) * Fix table centering (#599) -v0.3.0 -====== +0.3.0 +===== **Note**: this version resulted in some JavaScript incompatibilities when used on readthedocs.org @@ -248,40 +289,40 @@ Other Changes * Compress our Javascript files * Updated dependencies -v0.2.4 -====== +0.2.4 +===== * Yet another patch to deal with extra builders outside Spinx, such as the singlehtml builders from the Read the Docs Sphinx extension -v0.2.3 -====== +0.2.3 +===== * Temporarily patch Sphinx issue with ``singlehtml`` builder by inspecting the builder in template. -v0.2.2 -====== +0.2.2 +===== * Roll back toctree fix in 0.2.1 (#367). This didn't fix the issue and introduced another bug with toctrees display. -v0.2.1 -====== +0.2.1 +===== * Add the ``rel`` HTML attribute to the footer links which point to the previous and next pages. * Fix toctree issue caused by Sphinx singlehtml builder (#367) -v0.2.0 -====== +0.2.0 +===== * Adds the ``comments`` block after the ``body`` block in the template * Added "Edit on GitLab" support * Many bug fixes -v0.1.10-alpha -============= +0.1.10-alpha +============ .. note:: This is a pre-release version @@ -290,8 +331,8 @@ v0.1.10-alpha * Adds a ``body_begin`` block to the template * Added ``prev_next_buttons_location`` -v0.1.9 -====== +0.1.9 +===== * Intermittent scrollbar visibility bug fixed. This change introduces a backwards incompatible change to the theme's layout HTML. This should only be @@ -307,8 +348,8 @@ v0.1.9 .. _#215: https://github.com/rtfd/sphinx_rtd_theme/pull/215 -v0.1.8 -====== +0.1.8 +===== * Start keeping changelog :) * Support for third and fourth level headers in the sidebar diff --git a/docs/contributing.rst b/docs/contributing.rst index 54991d9..9eedb03 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -175,7 +175,7 @@ To release a new version of the theme, core team will take the following steps: #. Bump the version by running ``bump2version [major|minor|patch|dev]``. This will automatically increase the correct part(s) of the version number, you do not need to specify the exact version number. - We follow `semver <http://semver.org/>`_ and `PEP440`_ + We follow `semantic versioning`_ and `PEP440`_ (with regards to alpha release and development versions). The version increment should reflect these releases and any potentially breaking changes. #. New versions are by default ``alpha`` releases. If this is a release candidate, @@ -197,4 +197,9 @@ To release a new version of the theme, core team will take the following steps: $ python setup.py sdist bdist_wheel $ twine upload --sign --identity security@readthedocs.org dist/* +#. Finally, open a new pull request updating the development release version to + the next patch by running ``bump2version patch``. Open a pull request with + this change. + .. _PEP440: https://www.python.org/dev/peps/pep-0440/ +.. _semantic versioning: http://semver.org/ diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..1bf607d --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,180 @@ +Development +=========== + +The theme developers follow the guidelines below for development and release +planning. Documentation authors can decide which theme release works best for +their project based on required browser/operating system combinations or +dependency support. + +.. _supported-browsers: + +Supported browsers +------------------ + +Official browser support is determined by the most popular browser/operating +system combinations in our pageview analytics. Officially supported combinations +are commonly tested during development, and are always tested before final +release of a new version of the theme. + +Older releases of supported combinations, and some less common combinations, are +considered partially supported. This means that we do not consistently test +these combinations, however we do expect user experience to be comparable with +supported combinations. + +.. csv-table:: Supported browser combinations + :widths: 6, 12, 4 + :header-rows: 1 + :file: supported-browsers.csv + +.. versionadded:: 1.0 + Supported browser and operating system combinations added + +There are several browser/operating system combinations that are not supported +by the theme developers at all. Unsupported combinations do not receive testing +or development, and we likely won't accept major contributions for these +combinations. + +Unsupported browser/operating system combinations include: + +Internet Explorer (any OS, versions <=10) + **Unsupported.** IE11 is the last partially supported version. We do no + testing on prior versions. + +Internet Explorer (any OS, version 11) + We currently only partially support IE11, and only test for major bugs. + Support will be removed in the :ref:`2.0.0` release. + +Opera (any OS, any version) + **Community support only.** We do not receive enough traffic with this + browser to officially support it in testing and development. + +.. _supported-dependencies: + +Supported dependencies +---------------------- + +The theme officially supports the following dependencies in your Sphinx project: + +.. list-table:: Supported dependencies + :header-rows: 1 + :widths: 10, 10 + + * - Dependency + - Versions + * - Python + - 2.7 or 3.6 or greater + * - Sphinx + - 1.7 up to at least 4.1 + * - docutils + - Up to 0.17 + +.. versionadded:: 1.0 + Sphinx 4.0 support added + +.. deprecated:: 1.0 + Sphinx 1.6 support removed + +.. versionadded:: 1.0 + docutils 0.17 support added + +Roadmap +------- + +We currently have several releases planned on our development roadmap. Backward +incompatible changes, deprecations, and major features are noted for each of +these releases. + +Releases follow `semantic versioning`_, and so it is generally recommended that +authors pin dependency on ``sphinx_rtd_theme`` to a version below the next major +version: + +.. code:: console + + $ pip install "sphinx_rtd_theme<=2.0.0" + +.. _semantic versioning: http://semver.org/ + +.. _release-1.0.0: + +1.0.0 +~~~~~ + +:Planned release date: August 2021 + +This release will be a slightly backwards incompatible release to follow the +:ref:`0.5.2` release. It will drop support for Sphinx 1.6, which is a rather old +release at this point. + +This version will add official support for the Sphinx 4.x release series and +it resolves bugs with the latest release of Docutils, version 0.17. + +Starting with this release, several deprecation warnings will be emitted at +build time: + +Direct installation is deprecated + Support for direct installation through GitHub is no longer a suggested + installation method. In an effort to ease maintenance, compiled assets will + eventually be removed from the theme repository. These files will only be + included in the built packages/releases available on PyPI. + + We plan to start putting development releases up on PyPI more frequently, so + that installation from the theme source repository is no longer necessary. + + Built assets are tentatively planned to be removed in version :ref:`3.0.0`:. + +HTML4 support is deprecated + Support for the Sphinx HTML4 writer will be removed in the :ref:`2.0.0` + release. + +.. _release-1.1.0: + +1.1.0 +~~~~~ + +:Planned release date: 2021 Q3 + +We aim to follow up release :ref:`1.0.0` with at least one bug fix release in +the 1.x release series. The 1.1 release will not be adding any major features +and will instead mark the last release targeting projects with old dependencies +like Sphinx 1.8, HTML4, or required support for IE11. + +.. _release-2.0.0: + +2.0.0 +~~~~~ + +:Planned release date: 2022 Q1 + +This release will mark the beginning of a new round of feature development, as +well as a number of backward incompatible changes and deprecations. + +Of note, the following backwards incompatible changes are planned for this +release: + +Sphinx 1.x, Sphinx 2.x, and Docutils 0.16 will not be tested + Official support will drop for these version, though they may still continue + to work. Theme developers will not be testing these versions any longer. + +HTML4 support will be removed + Starting with this release, we will only support the HTML5 writer output, + and builds attempting to use the HTML4 writer will fail. If you are still + using the HTML4 writer, or have the ``html4_writer = True`` option in your + Sphinx configuration file, you will need to either remove this option or pin + your dependency to ``sphinx_rtd_theme<=2.0.0`` until you can. + + This option was suggested in the past to work around issues with HTML5 + support and should no longer be required to use a modern combination of this + theme and Sphinx. + +.. _release-3.0.0: + +3.0.0 +~~~~~ + +This release is not yet planned, however there are plans to potentially replace +Wyrm with Bootstrap in a release after 2.0. + +Also tentatively planned for this release is finally removing built CSS and +JavaScript assets from our repository. This will remove the ability to install +the package directly from GitHub, and instead users will be advised to install +development releases from PyPI diff --git a/docs/index.rst b/docs/index.rst index 615fd93..28bb8c0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,61 @@ -.. include:: ../README.rst +Read the Docs Sphinx Theme +========================== + +This Sphinx_ theme was designed to provide a great reader experience for +documentation users on both desktop and mobile devices. This theme is commonly +used with projects on `Read the Docs`_ but can work with any Sphinx project. + +.. _Sphinx: http://www.sphinx-doc.org +.. _Read the Docs: http://www.readthedocs.org + +Using this theme +---------------- + +:doc:`installing` + How to install this theme on your Sphinx project. + +:doc:`configuring` + Theme configuration and customization options. + +:ref:`supported-browsers` + Supported browser/operating system combinations. + +:ref:`supported-dependencies` + Supported project dependencies, like Python and Sphinx. + +Development +----------- + +:doc:`contributing` + How to contribute changes to the theme. + +:doc:`Development guidelines <development>` + Guidelines the theme developers use for developing and testing changes. + +`Read the Docs contributor guide`_ + Our contribution guidelines extend to all projects maintained by Read the + Docs core team. + +:doc:`changelog` + The theme development changelog. + +:doc:`Demo documentation <demo/structure>` + The theme's styleguide test environment, where new changes are tested. + + +.. _Read the Docs contributor guide: https://docs.readthedocs.io/en/stable/contribute.html + + +.. Hidden TOCs .. toctree:: :caption: Theme Documentation :maxdepth: 2 + :hidden: installing configuring + development contributing .. toctree:: @@ -18,6 +68,7 @@ :maxdepth: 2 :numbered: :caption: Demo Documentation + :hidden: demo/structure demo/demo @@ -28,5 +79,6 @@ :maxdepth: 3 :numbered: :caption: This is an incredibly long caption for a long menu + :hidden: demo/long diff --git a/docs/installing.rst b/docs/installing.rst index 61aaac1..522b986 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -1,6 +1,5 @@ -************ Installation -************ +============ Install the package (or add it to your ``requirements.txt`` file): @@ -21,6 +20,12 @@ In your ``conf.py`` file: html_theme = "sphinx_rtd_theme" +.. seealso:: + :ref:`supported-browsers` + Officially supported and tested browser/operating system combinations + + :ref:`supported-dependencies` + Officially Supported versions of Python, Sphinx, and other dependencies. .. note:: @@ -30,12 +35,13 @@ In your ``conf.py`` file: are using an old version of the theme. Via Git or Download -=================== +------------------- .. warning:: - Installing directly from the repo is deprecated. - Static assets won't be included in the repo in a future release. + 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:`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 @@ -45,19 +51,3 @@ Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into you html_theme = "sphinx_rtd_theme" html_theme_path = ["_themes", ] - -Compatibility -============= - -Python ------- - -``sphinx_rtd_theme`` requires Python 2.7 or Python 3.4 or greater. - -Sphinx ------- - -``sphinx_rtd_theme`` depends on at least Sphinx 1.6 although, -we recommend at least Sphinx 2 to take advantage of the html5 writer. -The html4 writer is still supported however, -it is deprecated and support will be removed in the near future. diff --git a/docs/supported-browsers.csv b/docs/supported-browsers.csv new file mode 100644 index 0000000..7e446d9 --- /dev/null +++ b/docs/supported-browsers.csv @@ -0,0 +1,5 @@ +Browser,Operating System,Versions +Chrome,"Windows, MacOS, Linux, Android",>=90 +Firefox,"Linux, Windows",>=90 +Edge,Windows,>=90 +Safari,"MacOS, iOS",>=13 |