Fix doc build

sunpy · May 15, 2024 · fff1411 · fff1411
1 parent 3dd6149
commit fff1411
Show file tree

Hide file tree

Showing 9 changed files with 15 additions and 13 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -125,7 +125,7 @@ New Features
 - Adds two tutorials that demonstrate how to use LASCO data in overlaying maps (:ref:`sphx_glr_generated_gallery_plotting_lasco_overlay.py`) and how to create a custom mask for a LASCO C2 image (:ref:`sphx_glr_generated_gallery_map_lasco_mask.py`). (`#6576 <https://github.com/sunpy/sunpy/pull/6576>`__)
 - Able to run the ``sunpy`` tests doing ``python -m sunpy.tests.self_test``. (`#6600 <https://github.com/sunpy/sunpy/pull/6600>`__)
 - Able to detect gzip-compressed FITS files even if they don't have the ``.gz`` extension in the filename.
-  `~sunpy.io.detect_filetype` now looks for the right file signature while checking
+  ``sunpy.io.detect_filetype`` now looks for the right file signature while checking
   for gzipped FITS files. (`#6693 <https://github.com/sunpy/sunpy/pull/6693>`__)
 - Added ``AttrAnd`` and ``AttrOr`` to the namespace in ``sunpy.net.attrs``.
   This allows users to to avoid ``|`` or ``&`` when creating a query a larger query. (`#6708 <https://github.com/sunpy/sunpy/pull/6708>`__)
@@ -850,7 +850,7 @@ Bug Fixes
   location was a fully specified Stonyhurst heliographic coordinate. (`#5584 <https://github.com/sunpy/sunpy/pull/5584>`__)
 - `~sunpy.map.sources.XRTMap` uppercases the ``TIMESYS`` key before checking if the
   key needs to be fixed. (`#5592 <https://github.com/sunpy/sunpy/pull/5592>`__)
-- Fixed passing a URL to :func:`sunpy.io.read_file` on windows. (`#5601 <https://github.com/sunpy/sunpy/pull/5601>`__)
+- Fixed passing a URL to ``sunpy.io.read_file`` on windows. (`#5601 <https://github.com/sunpy/sunpy/pull/5601>`__)
 - Fixed a bug where the ``date`` property on `~sunpy.map.sources.HMISynopticMap` returned ``None``
   if the ``DATE-OBS`` key was present. (`#5648 <https://github.com/sunpy/sunpy/pull/5648>`__)
 
@@ -1718,7 +1718,7 @@ Improved Documentation
   The page :ref:`sunpy-topic-guide-coordinates-rotatedsunframe` has an example of a mini-gallery at the bottom. (`#4124 <https://github.com/sunpy/sunpy/pull/4124>`__)
 - Added `sunpy.visualization.colormaps.color_tables` to the docs. (`#4182 <https://github.com/sunpy/sunpy/pull/4182>`__)
 - Made minor improvements to the map histogramming example. (`#4205 <https://github.com/sunpy/sunpy/pull/4205>`__)
-- Add a warning to `sunpy.io` docs to recommend not using it for FITS (`#4208 <https://github.com/sunpy/sunpy/pull/4208>`__)
+- Add a warning to ``sunpy.io`` docs to recommend not using it for FITS (`#4208 <https://github.com/sunpy/sunpy/pull/4208>`__)
 
 
 Trivial/Internal Changes
@@ -1824,7 +1824,7 @@ Features
   objects. (`#3408 <https://github.com/sunpy/sunpy/pull/3408>`__)
 - `~sunpy.map.GenericMap` objects now have a ``.cmap`` attribute, which returns the full `~matplotlib.colors.Colormap`.
   object. (`#3412 <https://github.com/sunpy/sunpy/pull/3412>`__)
-- `sunpy.io.write_file()` now accepts `~pathlib.Path` objects as filename inputs. (`#3469 <https://github.com/sunpy/sunpy/pull/3469>`__)
+- ``sunpy.io.write_file`` now accepts `~pathlib.Path` objects as filename inputs. (`#3469 <https://github.com/sunpy/sunpy/pull/3469>`__)
 - :func:`sunpy.map.header_helper.make_fitswcs_header` now accepts a `tuple` representing the shape of an array as well as the actual array as the ``data`` argument. (`#3483 <https://github.com/sunpy/sunpy/pull/3483>`__)
 - Made a couple of module imports lazy to reduce the import time of sunpy.map by
   ~40%. (`#3495 <https://github.com/sunpy/sunpy/pull/3495>`__)

diff --git a/changelog/6736.feature.rst b/changelog/6736.feature.rst
@@ -1 +1 @@
-:func:`sunpy.io.read_file` will now try to detect the filetype based on the content and then fallback to using the file extension.
+``sunpy.io.read_file`` will now try to detect the filetype based on the content and then fallback to using the file extension.
diff --git a/changelog/7537.breaking.rst b/changelog/7537.breaking.rst
@@ -1,2 +1,2 @@
-`sunpy.io.read_file` and `sunpy.io.write_file` are deprecated and will be removed in the future.
+``sunpy.io.read_file`` and ``sunpy.io.write_file`` are deprecated and will be removed in the future.
 These were intended to be private functions and should not be used.
diff --git a/docs/conf.py b/docs/conf.py
@@ -59,6 +59,7 @@
 
 # We want to make sure all the following warnings fail the build
 warnings.filterwarnings("error", category=SunpyDeprecationWarning)
+warnings.filterwarnings("ignore", message="The toplevel space of the io subpackage was never intended", category=SunpyDeprecationWarning)
 warnings.filterwarnings("error", category=SunpyPendingDeprecationWarning)
 warnings.filterwarnings("error", category=MatplotlibDeprecationWarning)
 warnings.filterwarnings("error", category=AstropyDeprecationWarning)

diff --git a/docs/how_to/index.rst b/docs/how_to/index.rst
@@ -13,13 +13,14 @@ If you're starting fresh you might want to check out the :ref:`sunpy-tutorial-in
 
    coord_components
    create_a_map
-   create_rectangle_on_map
    create_coords
    create_custom_map
    create_custom_timeseries
+   create_rectangle_on_map
    fix_map_metadata
    manipulate_grid_lines
    parse_time
+   read_asdf_file
    remote_data_manager
    search_multiple_wavelengths
    search_vso

diff --git a/docs/reference/io.rst b/docs/reference/io.rst
@@ -1,5 +1,5 @@
-Input/output (`sunpy.io`)
-*************************
+Input/output (``sunpy.io``)
+***************************
 
 The primary focus of ``sunpy.io`` is to provide a common interface for reading and writing.
 ``sunpy.io`` contains readers for files that are commonly used in solar physics.

diff --git a/pytest.ini b/pytest.ini
@@ -86,4 +86,4 @@ filterwarnings =
     # Latest version of parfive raises this warning
     ignore:This download has been started in a thread which is not the main thread:UserWarning
     # We deprecated the io top level and it triggers this warning now
-    #ignore:The toplevel space of the io subpackage was never
+    ignore:The toplevel space of the io subpackage was never
diff --git a/sunpy/io/_file_tools.py b/sunpy/io/_file_tools.py
@@ -125,7 +125,7 @@ def read_file_header(filepath, filetype=None, **kwargs):
     """
     Reads the header from a given file.
 
-    This should always return a instance of `~sunpy.io.header.FileHeader`.
+    This should always return a instance of `~sunpy.io._header.FileHeader`.
 
     Parameters
     ----------

diff --git a/sunpy/timeseries/timeseries_factory.py b/sunpy/timeseries/timeseries_factory.py
@@ -91,7 +91,7 @@ class TimeSeriesFactory(BasicRegistrationFactory):
     >>> my_timeseries = sunpy.timeseries.TimeSeries(data, header)  # doctest: +SKIP
     >>> my_timeseries = sunpy.timeseries.TimeSeries(data, header, units)  # doctest: +SKIP
 
-    * File names for files understood by `sunpy.io` and those not
+    * File names for files understood by the file reader and for those that are not
 
     >>> my_timeseries = sunpy.timeseries.TimeSeries('filename.fits')   # doctest: +SKIP
     >>> my_timeseries = sunpy.timeseries.TimeSeries('filename.fits', source='lyra')  # doctest: +SKIP
@@ -127,7 +127,7 @@ class TimeSeriesFactory(BasicRegistrationFactory):
     @staticmethod
     def _read_file(fname, **kwargs):
         """
-        Reading a file with `sunpy.io` for automatic source detection.
+        Reading a file with automatic source detection.
 
         Parameters
         ----------