Update API docstrings (#50)

This commit squashed together 26 commits:
* refactor: 🗑️ Deprecate "add_header_to_table"

* docs: ✍️ State deprecation of add_header_to_table in summary

* docs: ✍️ Update docstring for descriptor decorator.

* docs: ✍️ Update astro_data_tag documentation.

* docs: ✍️ Update returns_list documentation.

* docs(api): ✍️ Update from_file documentation

* docs(api): ✍️ Update open docstring

* docs: 👷 Add nox, install help.

* docs: ✍️ Unify and expand on docstrings in AstoData

* docs: ✍️ Unify and update nddata.py docs

* docs: ✍️ Update and unify docstrings for utils.

* docs: ✍️ Add examples and clarification to Section

* docs: 🧹 Fix docstring lint errors

* docs: ✍️ Fix linting errors for fits.py

* docs: ✍️ Rename Parameters to Arguments in docstrings

* docs: 🧹 Fix docstirng lint errors.

* docs: 🎨 Change Parameters to Arguments in docstring

* docs: 🧹 Fix testing docstring lint errors.

* ci(lint): ✨ Add documentation style rules to linter

* docs: 🧹 Fix wcs docstring lint errors.

* docs: 🧹 Change Parameter to Arguments in docstrings

* docs: 🧹 Fix provenance docstring lint errors.

* docs: 🧹 Fix docstring lint errors.

* docs: ✍️ Add information to package docstring.

* docs: 🧹 Change Parameters to Arguments where lingering.

* docs: 🚨 Fix line length problems.

astrodata/__init__.py

@@ -1,8 +1,19 @@
-"""This package adds an abstraction layer to astronomical data by parsing the
+"""Entry point for the |astrodata| package.
+
+This package adds an abstraction layer to astronomical data by parsing the
 information contained in the headers as attributes. To do so, one must subclass
 :class:`astrodata.AstroData` and add parse methods accordingly to the
 :class:`~astrodata.TagSet` received.
 
+For more information, you can build the documentation locally by running
+
+.. code-block:: bash
+
+    nox -s docs
+
+and opening the file ``_build/html/index.html`` in a browser. Alternatively,
+you can check the online documentation at
+`the |astrodata| pages site <https://geminidrsoftware.github.io/astrodata/>`_.
 """
 
 import importlib.metadata
@@ -64,28 +75,90 @@ def version():
 def from_file(*args, **kwargs):
     """Return an |AstroData| object from a file.
 
+    Arguments
+    ---------
+    source: str, os.PathLike or HDUList
+        The path to the file or the HDUList object. If a string is passed, it
+        will be treated as a path to a file.
+
+    Returns
+    -------
+    AstroData
+        An instantiated object. It will be a subclass of |AstroData|.
+
+    Notes
+    -----
     For implementation details, see
-    :meth:`~astrodata.AstroDataFactory.get_astro_data`.
+    :py:meth:`~astrodata.AstroDataFactory.get_astro_data`.
+
+    This function is a wrapper around the factory method
+    :py:meth:`~astrodata.AstroDataFactory.get_astro_data`, and uses the
+    default factory instance at :py:attr:`~astrodata.factory`. If you want to
+    override the default factory, you can create a new instance of
+    :py:class:`~astrodata.AstroDataFactory` and use its methods directly, or
+    assign it to :py:attr:`~astrodata.factory`.
+
+    Example
+    -------
+
+    >>> from astrodata import from_file
+    >>> ad = from_file("path/to/file.fits")
+
+    Alternatively, you can use an :py:class:`~astropy.io.fits.HDUList` object:
+
+    >>> from astropy.io import fits
+    >>> hdulist = fits.open("path/to/file.fits")
+    >>> ad = from_file(hdulist)
+
+    Which can be useful for inspecting input before creating the |AstroData|
+    object. This will not use the normal |AstroData| lazy-loading mechanism,
+    however.
     """
     return factory.get_astro_data(*args, **kwargs)
 
 
 def create(*args, **kwargs):
     """Return an |AstroData| object from data.
 
-    For implementation details, see
-    :meth:`~astrodata.AstroDataFactory.create_from_scratch`
+    Arguments
+    ---------
+    phu : `fits.PrimaryHDU` or `fits.Header` or `dict` or `list`
+        FITS primary HDU or header, or something that can be used to create
+        a fits.Header (a dict, a list of "cards").
+
+    extensions : list of HDUs
+        List of HDU objects.
+
+    Returns
+    -------
+    `astrodata.AstroData`
+        An AstroData instance.
+
+    Raises
+    ------
+    ValueError
+        If ``phu`` is not a valid object.
+
+    Example
+    -------
+
+    >>> from astrodata import create
+    >>> ad = create(phu=fits.PrimaryHDU(), extensions=[fits.ImageHDU()])
     """
     return factory.create_from_scratch(*args, **kwargs)
 
 
 # Without raising a warning or error.
 @deprecated(
     "Use 'astrodata.from_file'. astrodata.open is deprecated, "
-    "and will be removed in a future version."
+    "and will be removed in a future version. They take the "
+    "same arguments and return the same object.",
 )
 def open(*args, **kwargs):  # pylint: disable=redefined-builtin
-    """Return an |AstroData| object from a file (deprecated, use
-    :func:`~astrodata.from_file`).
+    """Return an |AstroData| object from a file.
+
+    .. warning::
+        This function is deprecated and will be removed in a future version.
+        Use :py:func:`~astrodata.from_file` instead.
     """
     return from_file(*args, **kwargs)

astrodata/adfactory.py

@@ -38,13 +38,15 @@ def registry(self):
         "astrodata.factory.AstroDataFactory._open_file"
     )
     @contextmanager
-    def _openFile(source):  # pylint: disable=invalid-name
+    def _openFile(source):  # noqa
         return AstroDataFactory._open_file(source)
 
     @staticmethod
     @contextmanager
     def _open_file(source):
-        """Internal static method that takes a ``source``, assuming that it is
+        """Open a file and return an appropriate object.
+
+        Internal static method that takes a ``source``, assuming that it is
         a string pointing to a file to be opened.
 
         If this is the case, it will try to open the file and return an
@@ -81,7 +83,7 @@ def _open_file(source):
                 except KeyboardInterrupt:
                     raise
 
-                except Exception as err:  # pylint: disable=broad-except
+                except Exception as err:  # noqa
                     LOGGER.error(
                         "Failed to open %s with %s, got error: %s",
                         source,
@@ -109,15 +111,18 @@ def _open_file(source):
         "Renamed to add_class, please use that method instead: "
         "astrodata.factory.AstroDataFactory.add_class"
     )
-    def addClass(self, cls):  # pylint: disable=invalid-name
-        """Add a new class to the AstroDataFactory registry. It will be used
-        when instantiating an AstroData class for a FITS file.
+    def addClass(self, cls):  # noqa
+        """Add a new class to the |AstroDataFactory| registry.
+
+        It will be used when instantiating an AstroData class for a FITS file.
         """
         self.add_class(cls)
 
     def add_class(self, cls):
-        """Add a new class to the AstroDataFactory registry. It will be used
-        when instantiating an AstroData class for a FITS file.
+        """Add a new class to the |AstroDataFactory|'s registry.
+
+        Add a new class to the |AstroDataFactory| registry. It will be used
+        when instantiating an |AstroData| class for a FITS file.
         """
         if not hasattr(cls, "_matches_data"):
             raise AttributeError(
@@ -137,12 +142,17 @@ def remove_class(self, cls: type | str):
         "Renamed to get_astro_data, please use that method instead: "
         "astrodata.factory.AstroDataFactory.get_astro_data"
     )
-    def getAstroData(self, source):  # pylint: disable=invalid-name
-        """Deprecated, see |get_astro_data|."""
+    def getAstroData(self, source):  # noqa
+        """Return an |AstroData| instance from a file or HDUList.
+
+        Deprecated, see |get_astro_data|.
+        """
         self.get_astro_data(source)
 
     def get_astro_data(self, source):
-        """Takes either a string (with the path to a file) or an HDUList as
+        """Return an |AstroData| instance from a file or HDUList.
+
+        Takes either a string (with the path to a file) or an HDUList as
         input, and tries to return an AstroData instance.
 
         It will raise exceptions if the file is not found, or if there is no
@@ -151,10 +161,15 @@ def get_astro_data(self, source):
         Returns an instantiated object, or raises AstroDataError if it was
         not possible to find a match
 
-        Parameters
-        ----------
+        Arguments
+        ---------
         source : `str` or `pathlib.Path` or `fits.HDUList`
             The file path or HDUList to read.
+
+        Returns
+        -------
+        `astrodata.AstroData`
+            An AstroData instance.
         """
         candidates = []
         with self._open_file(source) as opened:
@@ -204,15 +219,18 @@ def createFromScratch(
         self,
         phu,
         extensions=None,
-    ):  # pylint: disable=invalid-name
-        """Deprecated, see |create_from_scratch|."""
+    ):  # noqa
+        """Create an AstroData object from a collection of objects.
+
+        Deprecated, see |create_from_scratch|.
+        """
         self.create_from_scratch(phu=phu, extensions=extensions)
 
     def create_from_scratch(self, phu, extensions=None):
-        """Creates an AstroData object from a collection of objects.
+        """Create an AstroData object from a collection of objects.
 
-        Parameters
-        ----------
+        Arguments
+        ---------
         phu : `fits.PrimaryHDU` or `fits.Header` or `dict` or `list`
             FITS primary HDU or header, or something that can be used to create
             a fits.Header (a dict, a list of "cards").