[PATCH] docs: doc-guide: clarify latest theme usage

[PATCH] docs: doc-guide: clarify latest theme usage

[Randy Dunlap]

We have been using the Alabaster theme as the default theme since
Sept. 2022.

Keep the information on the RTD theme around in case someone wants to
try it with the DOCS_THEME environment variable.

Fixes: 26d797ffc1c0 ("docs: update sphinx.rst to reflect the default theme change")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
---
 Documentation/doc-guide/sphinx.rst |   12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

--- linux-next-20250516.orig/Documentation/doc-guide/sphinx.rst
+++ linux-next-20250516/Documentation/doc-guide/sphinx.rst
@@ -42,12 +42,6 @@ with your distributions. In order to do
 Sphinx inside a virtual environment, using ``virtualenv-3``
 or ``virtualenv``, depending on how your distribution packaged Python 3.
 
-.. note::
-
-   #) It is recommended to use the RTD theme for html output. Depending
-      on the Sphinx version, it should be installed separately,
-      with ``pip install sphinx_rtd_theme``.
-
 In summary, if you want to install the latest version of Sphinx, you
 should do::
 
@@ -162,6 +156,12 @@ By default, the "Alabaster" theme is use
 this theme is bundled with Sphinx and need not be installed separately.
 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
 
+.. note::
+
+   Some people might prefer to use the RTD theme for html output.
+   Depending on the Sphinx version, it should be installed separately,
+   with ``pip install sphinx_rtd_theme``.
+
 There is another make variable ``SPHINXDIRS``, which is useful when test
 building a subset of documentation.  For example, you can build documents
 under ``Documentation/doc-guide`` by running

Re: [PATCH] docs: doc-guide: clarify latest theme usage

[Mauro Carvalho Chehab]

Em Mon, 19 May 2025 15:36:13 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> We have been using the Alabaster theme as the default theme since
> Sept. 2022.
> 
> Keep the information on the RTD theme around in case someone wants to
> try it with the DOCS_THEME environment variable.
> 
> Fixes: 26d797ffc1c0 ("docs: update sphinx.rst to reflect the default theme change")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> ---
>  Documentation/doc-guide/sphinx.rst |   12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> --- linux-next-20250516.orig/Documentation/doc-guide/sphinx.rst
> +++ linux-next-20250516/Documentation/doc-guide/sphinx.rst
> @@ -42,12 +42,6 @@ with your distributions. In order to do
>  Sphinx inside a virtual environment, using ``virtualenv-3``
>  or ``virtualenv``, depending on how your distribution packaged Python 3.
>  
> -.. note::
> -
> -   #) It is recommended to use the RTD theme for html output. Depending
> -      on the Sphinx version, it should be installed separately,
> -      with ``pip install sphinx_rtd_theme``.
> -
>  In summary, if you want to install the latest version of Sphinx, you
>  should do::
>  
> @@ -162,6 +156,12 @@ By default, the "Alabaster" theme is use
>  this theme is bundled with Sphinx and need not be installed separately.
>  The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
>  
> +.. note::
> +
> +   Some people might prefer to use the RTD theme for html output.
> +   Depending on the Sphinx version, it should be installed separately,
> +   with ``pip install sphinx_rtd_theme``.
> +
>  There is another make variable ``SPHINXDIRS``, which is useful when test
>  building a subset of documentation.  For example, you can build documents
>  under ``Documentation/doc-guide`` by running



Thanks,
Mauro

Re: [PATCH] docs: doc-guide: clarify latest theme usage

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> We have been using the Alabaster theme as the default theme since
> Sept. 2022.
>
> Keep the information on the RTD theme around in case someone wants to
> try it with the DOCS_THEME environment variable.
>
> Fixes: 26d797ffc1c0 ("docs: update sphinx.rst to reflect the default theme change")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
>  Documentation/doc-guide/sphinx.rst |   12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)

Applied, thanks.

jon