Conditional documentation

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
 -----------------------------------
 

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

src/doc/en/reference/polynomial_rings/index.rst

@@ -65,9 +65,11 @@ Infinite Polynomial Rings
 Boolean Polynomials
 -------------------
 
-.. toctree::
-   :maxdepth: 1
+.. ONLY:: feature_sage_rings_polynomial_pbori
+
+   .. toctree::
+      :maxdepth: 1
 
-   sage/rings/polynomial/pbori/pbori
+      sage/rings/polynomial/pbori/pbori
 
 .. include:: ../footer.txt

src/sage_docbuild/conf.py

@@ -33,6 +33,7 @@
 from sage.env import SAGE_DOC_SRC, SAGE_DOC, THEBE_DIR, PPLPY_DOCS, MATHJAX_DIR
 from sage.misc.latex_macros import sage_mathjax_macros
 from sage.features import PythonModule
+from sage.features.all import all_features
 
 # General configuration
 # ---------------------
@@ -940,3 +941,18 @@ def setup(app):
         app.connect('missing-reference', find_sage_dangling_links)
         app.connect('builder-inited', nitpick_patch_config)
         app.connect('html-page-context', add_page_context)
+
+
+# Conditional content
+# https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tags
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#conf-tags
+# https://github.com/readthedocs/readthedocs.org/issues/4603#issuecomment-1411594800
+# Workaround to allow importing this file from other confs
+if 'tags' not in locals():
+    class Tags(set):
+        has = set.__contains__
+    tags = Tags()
+
+
+for feature in all_features():
+    tags.add('feature_' + feature.name.replace('.', '_'))