From fe5d82813434e7d7f9f33891da884d1533615933 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Sat, 7 Oct 2023 11:24:07 -0700 Subject: [PATCH 1/5] Conditionalize pbori documentation --- src/doc/en/reference/polynomial_rings/index.rst | 8 +++++--- src/sage_docbuild/conf.py | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/src/doc/en/reference/polynomial_rings/index.rst b/src/doc/en/reference/polynomial_rings/index.rst index b03fa4279ca..f03428e3595 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('.', '_')) From eec76cd5097dbc21df96de0ef99a6aa41160c14f Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Sat, 7 Oct 2023 15:45:18 -0700 Subject: [PATCH 2/5] 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 +` (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 From c5b566d228d17b807e3f40cd409fdcb75728201a Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 9 Oct 2023 08:34:03 -0700 Subject: [PATCH 3/5] Use uppercase .. ONLY:: --- src/doc/en/developer/sage_manuals.rst | 6 +++--- src/doc/en/reference/polynomial_rings/index.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/en/developer/sage_manuals.rst b/src/doc/en/developer/sage_manuals.rst index ec037f2ca9d..578419384c7 100644 --- a/src/doc/en/developer/sage_manuals.rst +++ b/src/doc/en/developer/sage_manuals.rst @@ -175,7 +175,7 @@ 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::" +directive ".. ONLY::" `_. Because Sphinx tags have to use Python identifier syntax, Sage uses the format ``feature_``, followed by the feature name where dots are @@ -184,13 +184,13 @@ the previous examples would look as follows: .. CODE-BLOCK:: rest - .. only:: feature_graphviz + .. ONLY:: feature_graphviz and: .. CODE-BLOCK:: rest - .. only:: feature_sage_symbolic + .. ONLY:: feature_sage_symbolic .. _section-building-manuals: diff --git a/src/doc/en/reference/polynomial_rings/index.rst b/src/doc/en/reference/polynomial_rings/index.rst index f03428e3595..0035c50021f 100644 --- a/src/doc/en/reference/polynomial_rings/index.rst +++ b/src/doc/en/reference/polynomial_rings/index.rst @@ -65,7 +65,7 @@ Infinite Polynomial Rings Boolean Polynomials ------------------- -.. only:: feature_sage_rings_polynomial_pbori +.. ONLY:: feature_sage_rings_polynomial_pbori .. toctree:: :maxdepth: 1 From e2f56fdfcd6da3ea34aa6cc799bdd935d096dbec Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 16 Oct 2023 20:17:18 -0700 Subject: [PATCH 4/5] src/doc/en/developer/packaging_sage_library.rst: Use all-caps ONLY --- src/doc/en/developer/packaging_sage_library.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/en/developer/packaging_sage_library.rst b/src/doc/en/developer/packaging_sage_library.rst index af1da6c674c..d8cd687ab79 100644 --- a/src/doc/en/developer/packaging_sage_library.rst +++ b/src/doc/en/developer/packaging_sage_library.rst @@ -479,7 +479,7 @@ 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 ::``, +should be conditionalized using the Sphinx directive ``.. ONLY ::``, as explained in :ref:`section-documentation-conditional`. From 4abc647ed9afc4abe195992d0eac3e70ca2a0338 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 17 Oct 2023 11:23:46 -0700 Subject: [PATCH 5/5] src/doc/en/developer/packaging_sage_library.rst: No space between ONLY and :: --- src/doc/en/developer/packaging_sage_library.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/en/developer/packaging_sage_library.rst b/src/doc/en/developer/packaging_sage_library.rst index d8cd687ab79..3b8ebbadf36 100644 --- a/src/doc/en/developer/packaging_sage_library.rst +++ b/src/doc/en/developer/packaging_sage_library.rst @@ -479,7 +479,7 @@ 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 ::``, +should be conditionalized using the Sphinx directive ``.. ONLY::``, as explained in :ref:`section-documentation-conditional`.