From 748f9c9b82515a45b34cea7d0347fbf0a7ffcfe7 Mon Sep 17 00:00:00 2001
From: Matthias Koeppe <mkoeppe@math.ucdavis.edu>
Date: Sat, 7 Oct 2023 15:45:18 -0700
Subject: [PATCH] src/doc/en/developer: Document how to conditionalize portions
 of the manual

---
 .../en/developer/packaging_sage_library.rst   | 11 ++++++++
 src/doc/en/developer/sage_manuals.rst         | 26 +++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/src/doc/en/developer/packaging_sage_library.rst b/src/doc/en/developer/packaging_sage_library.rst
index abda71bbed8..af1da6c674c 100644
--- a/src/doc/en/developer/packaging_sage_library.rst
+++ b/src/doc/en/developer/packaging_sage_library.rst
@@ -472,6 +472,17 @@ requiring all of Sage to be present.
 mechanism mentioned above can also be used for this.
 
 
+Dependencies of the Sage documentation
+--------------------------------------
+
+The documentation will not be modularized.
+
+However, some parts of the Sage reference manual may depend on functionality
+provided by optional packages. These portions of the reference manual
+should be conditionalized using the Sphinx directive ``.. only ::``,
+as explained in :ref:`section-documentation-conditional`.
+
+
 Version constraints of dependencies
 -----------------------------------
 
diff --git a/src/doc/en/developer/sage_manuals.rst b/src/doc/en/developer/sage_manuals.rst
index 30e8114175d..ec037f2ca9d 100644
--- a/src/doc/en/developer/sage_manuals.rst
+++ b/src/doc/en/developer/sage_manuals.rst
@@ -166,6 +166,32 @@ procedure is different:
 * Add your file to the index contained in
   ``SAGE_ROOT/src/doc/en/reference/combinat/module_list.rst``.
 
+.. _section-documentation-conditional:
+
+Making portions of the reference manual conditional on optional features
+========================================================================
+
+For every dynamically detectable feature such as :class:`graphviz
+<~sage.features.graphviz.Graphviz>` or :class:`sage.symbolic
+<sage.features.sagemath.sage__symbolic>` (see :mod:`sage.features`),
+Sage defines a Sphinx tag that can be used with the `Sphinx
+directive ".. only::"
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tags>`_.
+Because Sphinx tags have to use Python identifier syntax, Sage uses
+the format ``feature_``, followed by the feature name where dots are
+replaced by underscores. Hence, conditionalizing on the features of
+the previous examples would look as follows:
+
+.. CODE-BLOCK:: rest
+
+  .. only:: feature_graphviz
+
+and:
+
+.. CODE-BLOCK:: rest
+
+  .. only:: feature_sage_symbolic
+
 .. _section-building-manuals:
 
 Building the manuals