From 204ac80935eb82f7b32603f63a12b7f0651a17e6 Mon Sep 17 00:00:00 2001
From: Chris Johns <chrisj@rtems.org>
Date: Wed, 21 Feb 2024 16:07:04 +1100
Subject: sphinx: Use the pip installed sphinx-rtd-theme

- Remove the RTEMS version of the theme

- Use conf.py to specify our style sheet

- Depend on the jQuery contrib package for including jQuery

- Detect the theme is installed

Closes #4994
---
 README.txt | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

(limited to 'README.txt')

diff --git a/README.txt b/README.txt
index 1c4d729..de2313f 100644
--- a/README.txt
+++ b/README.txt
@@ -122,9 +122,29 @@ create a specific python environment using `pip`.
 
 Similarly, npm packages can be installed into a users $HOME directory.
 
+Versions
+~~~~~~~~
+
+  Sphinx                        7.2.6
+  sphinx-rtd-theme              2.0.0
+  sphinxcontrib-applehelp       1.0.7
+  sphinxcontrib-bibtex          2.6.1
+  sphinxcontrib-devhelp         1.0.5
+  sphinxcontrib-htmlhelp        2.0.4
+  sphinxcontrib-jquery          4.1
+  sphinxcontrib-jsmath          1.0.1
+  sphinxcontrib-qthelp          1.0.6
+  sphinxcontrib-serializinghtml 1.1.9
+
+
 Python Virtual Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The project recommends virtual environments for building RTEMS
+documentation using Sphinx. A virtual envionment lets you install and
+maintain a Sphinx build environment without installing and depending
+on system wide packages.
+
 Create a directory to house the virtual environment, create the environment,
 and then activate it. This example assumes Python3 and the `venv` module:
 
@@ -142,8 +162,11 @@ Either way, the prompt will now change. You can install Sphinx with:
 
   $ pip install sphinx
   $ pip install sphinxcontrib-bibtex
+  $ pip install sphinxcontrib-jquery
+  $ pip install sphinx-rtd-theme
 
-When you have finished you enter `deactivate`.
+When you have finished using sphinx and buildind documentation you
+enter `deactivate`.
 
 NPM Per User Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -166,6 +189,8 @@ does not provide a suitable package:
 
   $ pip install -U --user sphinx
   $ pip install --user sphinxcontrib-bibtex
+  $ pip install --user sphinxcontrib-jquery
+  $ pip install --user sphinx-rtd-theme
 
 On some hosts, this may complain that a newer version of pip is available.
 If so, then upgrade pip into your personal area.
@@ -209,6 +234,8 @@ Install Sphinx and any needed extensions:
 
  $ pip install sphinx
  $ pip install sphinxcontrib-bibtex
+ $ pip install sphinxcontrib-jquery
+ $ pip install sphinx-rtd-theme
 
 FreeBSD
 ~~~~~~~
@@ -217,7 +244,7 @@ PDF Quality: production
 
 Sphinx:
 
-  # pkg install py27-sphinx
+  Use a virtual environment and pip.
 
 PDF:
 
-- 
cgit v1.2.3