diff --git a/src/doc/en/developer/packaging_sage_library.rst b/src/doc/en/developer/packaging_sage_library.rst index abda71bbed8..3b8ebbadf36 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..578419384c7 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 +` (see :mod:`sage.features`), +Sage defines a Sphinx tag that can be used with the `Sphinx +directive ".. ONLY::" +`_. +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 diff --git a/src/doc/en/reference/polynomial_rings/index.rst b/src/doc/en/reference/polynomial_rings/index.rst index b03fa4279ca..0035c50021f 100644 --- a/src/doc/en/reference/polynomial_rings/index.rst +++ b/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 diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 5eca4ed29b0..0e3e857441d 100644 --- a/src/sage_docbuild/conf.py +++ b/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('.', '_'))