Add flags functions to Sphinx documentation

Author: asmeurer

array_api_strict/_flags.py

@@ -91,22 +91,20 @@ def set_array_api_strict_flags(
       array-api-strict. The default is ``{default_extensions}``. Note that
       some extensions require a minimum version of the standard.
 
-    The default values of the flags can also be changed by setting environment
-    variables:
-
-    - ``ARRAY_API_STRICT_API_VERSION``: A string representing the version number.
-    - ``ARRAY_API_STRICT_DATA_DEPENDENT_SHAPES``: "True" or "False".
-    - ``ARRAY_API_STRICT_ENABLED_EXTENSIONS``: A comma separated list of
-      extensions to enable.
+    The flags can also be changed by setting :ref:`environment variables
+    <environment-variables>`.
 
     Examples
     --------
 
     >>> from array_api_strict import set_array_api_strict_flags
+
     >>> # Set the standard version to 2021.12
     >>> set_array_api_strict_flags(api_version="2021.12")
+
     >>> # Disable data-dependent shapes
     >>> set_array_api_strict_flags(data_dependent_shapes=False)
+
     >>> # Enable only the linalg extension (disable the fft extension)
     >>> set_array_api_strict_flags(enabled_extensions=["linalg"])
 
@@ -192,13 +190,17 @@ def reset_array_api_strict_flags():
     """
     Reset the array-api-strict flags to their default values.
 
-    This will also reset any flags that were set by environment variables.
+    This will also reset any flags that were set by :ref:`environment
+    variables <environment-variables>` back to their default values.
 
     .. note::
 
        This function is **not** part of the array API standard. It only exists
        in array-api-strict.
 
+    See :func:`set_array_api_strict_flags` for a list of flags and their
+    default values.
+
     Examples
     --------
 
@@ -229,7 +231,7 @@ class ArrayAPIStrictFlags:
        This class is **not** part of the array API standard. It only exists
        in array-api-strict.
 
-    See :func:`~.array_api_strict.set_array_api_strict_flags` for a
+    See :func:`set_array_api_strict_flags` for a
     description of the available flags.
 
     See Also

docs/api.rst

@@ -0,0 +1,39 @@
+API Reference
+=============
+
+.. automodule:: array_api_strict
+
+Array API Strict Flags
+----------------------
+
+.. automodule:: array_api_strict._flags
+
+.. currentmodule:: array_api_strict
+
+.. autofunction:: get_array_api_strict_flags
+.. autofunction:: set_array_api_strict_flags
+.. autofunction:: reset_array_api_strict_flags
+.. autoclass:: ArrayAPIStrictFlags
+
+.. _environment-variables:
+
+Environment Variables
+~~~~~~~~~~~~~~~~~~~~~
+
+Flags can also be set with environment variables.
+:func:`set_array_api_strict_flags` will override the values set by environment
+variables. Note that the environment variables will only change the defaults
+used by array-api-strict initially. They will not change the defaults used by
+:func:`reset_array_api_strict_flags`.
+
+.. envvar:: ARRAY_API_STRICT_API_VERSION
+
+   A string representing the version number.
+
+.. envvar:: ARRAY_API_STRICT_DATA_DEPENDENT_SHAPES
+
+   "True" or "False" to enable or disable data dependent shapes.
+
+.. envvar:: ARRAY_API_STRICT_ENABLED_EXTENSIONS
+
+   A comma separated list of extensions to enable.

docs/changelog.md

@@ -20,7 +20,7 @@
 This is the first release of `array_api_strict`. It is extracted from
 `numpy.array_api`, which was included as an experimental submodule in NumPy
 versions prior to 2.0. Note that the commit history in this repository is
-extracted from the git history of numpy/array_api/ (see the [README](README.md)).
+extracted from the git history of numpy/array_api/ (see [](numpy.array_api)).
 
 Additionally, the following changes are new to `array_api_strict` from
 `numpy.array_api` in NumPy 1.26 (the last NumPy feature release to include

docs/conf.py

@@ -22,8 +22,8 @@
 
 extensions = [
     'myst_parser',
-    # 'sphinx.ext.autodoc',
-    # 'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
     # 'sphinx.ext.intersphinx',
     'sphinx_copybutton',
 ]

docs/index.md

@@ -183,6 +183,7 @@ issue, but this hasn't necessarily been tested thoroughly.
    API standard. [Support for 2023.12 is
    planned](https://github.com/data-apis/array-api-strict/issues/25).
 
+(numpy.array_api)=
 ## Relationship to `numpy.array_api`
 
 Previously this implementation was available as `numpy.array_api`, but it was
@@ -201,5 +202,6 @@ git_filter_repo.py --path numpy/array_api/ --path-rename numpy/array_api:array_a
 :titlesonly:
 :hidden:
 
+api.rst
 changelog.md
 ```