documentation

Signed-off-by: nstarman <nstarman@users.noreply.github.com>
Co-authored-by: Eero Vaher <eero.vaher@fysik.lu.se>
Signed-off-by: nstarman <nstarman@users.noreply.github.com>

Author: nstarman

astropy/cosmology/connect.py

@@ -33,10 +33,11 @@ def __getattr__(name):
 
     # Raise deprecation warning
     warnings.warn(
-        f"{name} is deprecated (since v6.0) and will be removed in a future version. "
+        f"astropy.cosmology.connect.{name} is deprecated (since v6.0)"
+        " and will be removed in a future version. "
         f"Use astropy.cosmology.io.{name} instead.",
         AstropyDeprecationWarning,
-        stacklevel=2,
+        stacklevel=1,
     )
 
     return obj

astropy/cosmology/io/_connect.py

@@ -17,6 +17,7 @@
 # Read / Write
 
 readwrite_registry = io_registry.UnifiedIORegistry()
+"""Registry for reading and writing cosmology objects."""
 
 
 class CosmologyRead(io_registry.UnifiedReadWrite):
@@ -139,6 +140,7 @@ def __call__(self, *args, **kwargs):
 # for transforming instances, e.g. Cosmology <-> dict
 
 convert_registry = io_registry.UnifiedIORegistry()
+"""Registry for converting cosmology objects to and from other formats."""
 
 
 class CosmologyFromFormat(io_registry.UnifiedReadWrite):

docs/changes/cosmology/14982.api.rst

@@ -1,3 +1,3 @@
-A new module -- ``astropy.cosmology.io`` -- has been added for all cosmology I/O
-functionality. ``astropy.cosmology.connect`` has been deprecated and will be removed in
-a future version; it's contents are now in ``astropy.cosmology.io``.
+``astropy.cosmology.connect`` has been renamed to ``astropy.cosmology.io``.
+The module is still available under its old name, but that has been deprecated
+and will be removed in a future version.

docs/cosmology/io/builtin.rst

@@ -69,6 +69,7 @@ Row
 .. automodule:: astropy.cosmology.io._builtin.row
 
 
+.. _cosmology_io_builtin_readwrite:
 
 *************************************
 Built-in Cosmology Read/Write Formats

docs/cosmology/io/details.rst

@@ -28,10 +28,8 @@ object is using the :mod:`pickle` module. This is good for e.g. passing a
 
 However this method has all the attendant drawbacks of :mod:`pickle` — security
 vulnerabilities and non-human-readable files. Pickle files just generally don't
-make for good persistent storage.
-
-Solving both these issues, ``astropy`` provides a unified interface for reading
-and writing data in different formats.
+make for good persistent storage. See :ref:`cosmology_io_builtin_readwrite` for
+better options.
 
 
 .. _cosmology_io_renaming_fields:

docs/cosmology/io/index.rst

@@ -9,9 +9,9 @@ Cosmology I/O & Convert
 Introduction
 ============
 
-The ``astropy.cosmology.io`` package provides a unified interface for reading, writing,
-and converting |Cosmology| objects. Most of the features of this package are accessible
-through the |Cosmology| class, which provides the methods |Cosmology.read|,
+The :mod:`astropy.cosmology.io` package provides a unified interface for reading,
+writing, and converting |Cosmology| objects. Most of the features of this package are
+accessible through the |Cosmology| class, which provides the methods |Cosmology.read|,
 |Cosmology.write|, |Cosmology.to_format|, and |Cosmology.from_format| for reading,
 writing, and converting |Cosmology| objects, respectively.
 
@@ -89,8 +89,8 @@ instances between packages!
 
 .. EXAMPLE START: Planck18 to QTable and back
 
-Another pre-registered format is "table", for converting a |Cosmology| to and
-from a |QTable|.
+One of the pre-registered conversion formats is "astropy.table", for converting a
+|Cosmology| to and from a |QTable|.
 
 .. code-block::
 
@@ -154,3 +154,5 @@ Reference/API
 =============
 
 .. automodapi:: astropy.cosmology.io
+   :no-heading:
+   :include-all-objects:

docs/cosmology/units.rst

@@ -23,8 +23,7 @@ for unit conversions and equivalencies, use
 About the Units
 ===============
 
-.. doctest::
-   :hide:
+.. testsetup::
 
    >>> import astropy.units as u
 

docs/whatsnew/6.0.rst

@@ -155,6 +155,27 @@ method, allowing users to export a cosmology object to a LaTeX table.::
 This will write the cosmology object to a file in LaTeX format,
 with appropriate formatting of units and table alignment.
 
+I/O Module
+----------
+
+The new :mod:`~astropy.cosmology.io` module contains the classes and functions that are
+used to read and write, cosmology instances to different file formats, and to convert
+cosmologies between different object representations. In particular, the
+:mod:`~astropy.cosmology.io` module provides the classes
+:class:`~astropy.cosmology.io.CosmologyRead`,
+:class:`~astropy.cosmology.io.CosmologyWrite`,
+:class:`~astropy.cosmology.io.CosmologyFromFormat`,
+:class:`~astropy.cosmology.io.CosmologyToFormat` and registries
+:obj:`~astropy.cosmology.io.readwrite_registry`,
+:obj:`~astropy.cosmology.io.convert_registry`, which enable
+:class:`~astropy.cosmology.Cosmology` class for |Cosmology.read|, |Cosmology.write|,
+|Cosmology.from_format|, and |Cosmology.to_format|.
+
+The public :mod:`~astropy.cosmology.io` module replaces the old semi-private
+:mod:`~astropy.cosmology.connect` module. It is intended that more public I/O
+functionality will be added to the :mod:`~astropy.cosmology.io` module in the future.
+
+
 Renaming fields in I/O
 ----------------------