sagemathgh-36495: Conditional documentation

    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes sagemath#1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->

<!-- Why is this change required? What problem does it solve? -->
Documentation is conditionalized by using Sphinx tags.

Split out from (and preparation for):
- sagemath#36380

Part of:
- sagemath#29705

<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes sagemath#12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [ ] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [x] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- sagemath#12345: short description why this is a dependency
- sagemath#34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: sagemath#36495
Reported by: Matthias Köppe
Reviewer(s): Kwankyu Lee

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

@@ -34,6 +34,7 @@
 from sage.env import SAGE_DOC_SRC, SAGE_DOC, 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
 # ---------------------
@@ -1051,3 +1052,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('.', '_'))