# Licensed under a 3-clause BSD style license - see LICENSE.rst
#
# Astropy documentation build configuration file.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this file.
#
# All configuration values have a default. Some values are defined in
# the global Astropy configuration which is loaded here before anything else.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('..'))
# IMPORTANT: the above commented section was generated by sphinx-quickstart, but
# is *NOT* appropriate for astropy or Astropy affiliated packages. It is left
# commented out with this explanation to make it clear why this should not be
# done. If the sys.path entry above is added, when the astropy.sphinx.conf
# import occurs, it will import the *source* version of astropy instead of the
# version installed (if invoked as "make html" or directly with sphinx), or the
# version in the build directory.
# Thus, any C-extensions that are needed to build the documentation will *not*
# be accessible, and the documentation will not build correctly.
# See sphinx_astropy.conf for which values are set there.

import doctest
import inspect
import operator
import os
import sys
import tomllib
import warnings
from datetime import UTC, datetime
from importlib import metadata
from pathlib import Path

import sphinx
from packaging.requirements import Requirement
from packaging.specifiers import SpecifierSet
from sphinx.util import logging

# xref: https://github.com/sphinx-doc/sphinx/issues/13232#issuecomment-2608708175
if sys.version_info[:2] >= (3, 13) and sphinx.version_info[:2] < (8, 2):
    import pathlib

    from sphinx.util.typing import _INVALID_BUILTIN_CLASSES

    _INVALID_BUILTIN_CLASSES[pathlib.Path] = "pathlib.Path"


# from docs import global_substitutions

logger = logging.getLogger(__name__)

# -- Check for missing dependencies -------------------------------------------
missing_requirements = {}
for line in metadata.requires("astropy"):
    if 'extra == "docs"' in line:
        req = Requirement(line.split(";")[0])
        req_package = req.name.lower()
        req_specifier = str(req.specifier)

        try:
            version = metadata.version(req_package)
        except metadata.PackageNotFoundError:
            missing_requirements[req_package] = req_specifier

        if version not in SpecifierSet(req_specifier, prereleases=True):
            missing_requirements[req_package] = req_specifier

if missing_requirements:
    msg = (
        "The following packages could not be found and are required to "
        "build the documentation:\n"
        "%s"
        '\nPlease install the "docs" requirements.',
        "\n".join([f"    * {key} {val}" for key, val in missing_requirements.items()]),
    )
    logger.error(msg)
    sys.exit(1)

from sphinx_astropy.conf.v2 import *  # noqa: E402, F403
from sphinx_astropy.conf.v2 import (  # noqa: E402
    exclude_patterns,
    extensions,
    html_theme_options,
    intersphinx_mapping,
    numpydoc_xref_aliases,
    numpydoc_xref_astropy_aliases,
    numpydoc_xref_ignore,
)

# -- Plot configuration -------------------------------------------------------
plot_rcparams = {
    "axes.labelsize": "large",
    "figure.figsize": (6, 6),
    "figure.subplot.hspace": 0.5,
    "savefig.bbox": "tight",
    "savefig.facecolor": "none",
}
plot_apply_rcparams = True
plot_html_show_source_link = False
plot_formats = ["png", "svg", "pdf"]
# Don't use the default - which includes a numpy and matplotlib import
plot_pre_code = ""

# -- General configuration ----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = "3.0"

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# .inc.rst mean *include* files, don't have sphinx process them
exclude_patterns += ["_templates", "changes", "_pkgtemplate.rst", "**/*.inc.rst"]

# Add any paths that contain templates here, relative to this directory.
if "templates_path" not in locals():  # in case parent conf.py defines it
    templates_path = []
templates_path.append("_templates")

extensions += [
    "sphinx_design",
]

# Grab minversion from pyproject.toml
with (Path(__file__).parents[1] / "pyproject.toml").open("rb") as f:
    pyproject = tomllib.load(f)

# Manually register doctest options since matplotlib 3.5 messed up allowing them
# from pytest-doctestplus
IGNORE_OUTPUT = doctest.register_optionflag("IGNORE_OUTPUT")
REMOTE_DATA = doctest.register_optionflag("REMOTE_DATA")
FLOAT_CMP = doctest.register_optionflag("FLOAT_CMP")

# Whether to create cross-references for the parameter types in the
# Parameters, Other Parameters, Returns and Yields sections of the docstring.
numpydoc_xref_param_type = True

# Words not to cross-reference. Most likely, these are common words used in
# parameter type descriptions that may be confused for classes of the same
# name. The base set comes from sphinx-astropy. We add more here.
numpydoc_xref_ignore.update(
    {
        "mixin",
        "Any",  # aka something that would be annotated with `typing.Any`
        # needed in subclassing numpy  # TODO! revisit
        "Arguments",
        "Path",
        # TODO! not need to ignore.
        "flag",
        "bits",
    }
)

# Mappings to fully qualified paths (or correct ReST references) for the
# aliases/shortcuts used when specifying the types of parameters.
# Numpy provides some defaults
# https://github.com/numpy/numpydoc/blob/b352cd7635f2ea7748722f410a31f937d92545cc/numpydoc/xref.py#L62-L94
# and a base set comes from sphinx-astropy.
# so here we mostly need to define Astropy-specific x-refs
numpydoc_xref_aliases.update(
    {
        # python & adjacent
        "Any": "`~typing.Any`",
        "file-like": ":term:`python:file-like object`",
        "file": ":term:`python:file object`",
        "path-like": ":term:`python:path-like object`",
        "module": ":term:`python:module`",
        "buffer-like": ":term:buffer-like",
        "hashable": ":term:`python:hashable`",
        # for matplotlib
        "color": ":term:`color`",
        # for numpy
        "ints": ":class:`python:int`",
        # for astropy
        "number": ":term:`number`",
        "Quantity": ":class:`~astropy.units.Quantity`",
        "Representation": ":class:`~astropy.coordinates.BaseRepresentation`",
        "writable": ":term:`writable file-like object`",
        "readable": ":term:`readable file-like object`",
        "BaseHDU": ":doc:`HDU </io/fits/api/hdus>`",
    }
)
# Add from sphinx-astropy 1) glossary aliases 2) physical types.
numpydoc_xref_aliases.update(numpydoc_xref_astropy_aliases)

# Turn off table of contents entries for functions and classes
toc_object_entries = False

# -- Project information ------------------------------------------------------

project = "Astropy"
author = "The Astropy Developers"
copyright = f"2011–{datetime.now(tz=UTC).year}, " + author

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.

# The full version, including alpha/beta/rc tags.
release = metadata.version(project)
# The short X.Y version.
version = ".".join(release.split(".")[:2])

# Only include dev docs in dev version.
dev = "dev" in release
if not dev:
    exclude_patterns += ["development/*"]

# -- Options for the module index ---------------------------------------------

modindex_common_prefix = ["astropy."]


# -- Options for HTML output ---------------------------------------------------

html_theme_options.update(
    {
        "github_url": "https://github.com/astropy/astropy",
        "external_links": [
            {"name": "Tutorials", "url": "https://learn.astropy.org/"},
        ],
        "use_edit_page_button": True,
        "logo": {
            "image_light": "_static/astropy_banner_96.png",
            "image_dark": "_static/astropy_banner_96_dark.png",
        },
        # https://github.com/pydata/pydata-sphinx-theme/issues/1492
        "navigation_with_keys": False,
        "announcement": "https://www.astropy.org/annoucement_banner.html",
    }
)

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
html_title = f"{project} v{release}"

html_favicon = "_static/astropy_logo.ico"
html_static_path = ["_static"]
html_css_files = ["astropy.css"]
html_copy_source = False

# Output file base name for HTML help builder.
htmlhelp_basename = project + "doc"

# Set canonical URL from the Read the Docs Domain
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")


def _custom_edit_url(
    github_user,
    github_repo,
    github_version,
    doc_path,
    file_name,
    default_edit_page_url_template,
):
    """Create custom 'edit' URLs for API modules since they are dynamically generated."""
    if file_name.startswith("api/astropy.") and file_name.endswith(".rst"):
        # this is a dynamically generated API page
        astropy_path = file_name.removeprefix("api/astropy.").removesuffix(".rst")
        item = operator.attrgetter(astropy_path)(astropy)  # noqa: F405
        if module := getattr(item, "__module__", None):
            mod_dir, _, mod_file = module.rpartition(".")
            new_file_name = mod_file + ".py"
            try:
                line_no = inspect.findsource(item)[1]
            except Exception:
                # Warn if not just a cosmology instance, or a wcs compiled function.
                if not (
                    (
                        "cosmology.realizations" in file_name
                        and not isinstance(item, type)
                    )
                    or "modeling.tabular.Tabular" in file_name
                    or "astropy.wcs" in file_name
                ):
                    warnings.warn(
                        f"could not find source for {doc_path=}, {file_name=}"
                    )
            else:
                new_file_name += f"#L{line_no + 1}"
            doc_path = mod_dir.replace(".", "/") + "/"
            file_name = new_file_name
        else:
            if "cosmology.realizations.available" in file_name:
                doc_path = "astropy/cosmology/"
                file_name = "realizations.py"
            else:
                warnings.warn(f"could not find module for {doc_path=}, {file_name=}")
                # Fall back for items that do not even have a module. Hope for the best.
                doc_path = "astropy"
                file_name = astropy_path.replace(".", "/")

    return default_edit_page_url_template.format(
        github_user=github_user,
        github_repo=github_repo,
        github_version=github_version,
        doc_path=doc_path,
        file_name=file_name,
    )


# A dictionary of values to pass into the template engine's context for all pages.
html_context = {
    "default_mode": "light",
    "version_slug": os.environ.get("READTHEDOCS_VERSION") or "",
    "to_be_indexed": ["stable", "latest"],
    "is_development": dev,
    "github_user": "astropy",
    "github_repo": "astropy",
    "github_version": "main",
    "doc_path": "docs",
    "edit_page_url_template": "{{ astropy_custom_edit_url(github_user, github_repo, github_version, doc_path, file_name, default_edit_page_url_template) }}",
    "default_edit_page_url_template": "https://github.com/{github_user}/{github_repo}/edit/{github_version}/{doc_path}{file_name}",
    "astropy_custom_edit_url": _custom_edit_url,
    # Tell Jinja2 templates the build is running on Read the Docs
    "READTHEDOCS": os.environ.get("READTHEDOCS", "") == "True",
}

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
html_extra_path = ["robots.txt"]

# -- Options for LaTeX output --------------------------------------------------

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
    ("index", project + ".tex", project + " Documentation", author, "manual")
]

latex_logo = "_static/astropy_logo.pdf"


# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [("index", project.lower(), project + " Documentation", [author], 1)]

# Setting this URL is required by sphinx-astropy
github_issues_url = "https://github.com/astropy/astropy/issues/"
edit_on_github_branch = "main"

# Enable nitpicky mode - which ensures that all references in the docs
# resolve.

nitpicky = True
show_warning_types = True
# See docs/nitpick-exceptions file for the actual listing.
nitpick_ignore = []
for line in open("nitpick-exceptions"):
    if line.strip() == "" or line.startswith("#"):
        continue
    dtype, target = line.split(None, 1)
    nitpick_ignore.append((dtype, target.strip()))

suppress_warnings = [
    "config.cache",  # our rebuild is okay
]

# -- Options for the Sphinx gallery -------------------------------------------

try:
    import warnings

    import sphinx_gallery

    extensions += ["sphinx_gallery.gen_gallery"]

    sphinx_gallery_conf = {
        "backreferences_dir": "generated/modules",  # path to store the module using example template
        "filename_pattern": "^((?!skip_).)*$",  # execute all examples except those that start with "skip_"
        "examples_dirs": f"..{os.sep}examples",  # path to the examples scripts
        "gallery_dirs": "generated/examples",  # path to save gallery generated examples
        "reference_url": {
            "astropy": None,
            "matplotlib": "https://matplotlib.org/stable/",
            "numpy": "https://numpy.org/doc/stable/",
        },
        "abort_on_example_error": True,
    }

    # Filter out backend-related warnings as described in
    # https://github.com/sphinx-gallery/sphinx-gallery/pull/564
    warnings.filterwarnings(
        "ignore",
        category=UserWarning,
        message=(
            "Matplotlib is currently using agg, which is a"
            " non-GUI backend, so cannot show the figure."
        ),
    )

except ImportError:
    sphinx_gallery = None


# -- Options for linkcheck output -------------------------------------------
linkcheck_retry = 5
linkcheck_ignore = [
    "https://journals.aas.org/manuscript-preparation/",
    "https://maia.usno.navy.mil/",
    "https://www.usno.navy.mil/USNO/time/gps/usno-gps-time-transfer",
    "https://aa.usno.navy.mil/publications/docs/Circular_179.php",
    "http://data.astropy.org",
    "https://doi.org/",  # CI blocked by service provider
    "https://ui.adsabs.harvard.edu",  # CI blocked by service provider
    "https://www.tandfonline.com/",  # 403 Client Error: Forbidden
    "https://stackoverflow.com/",  # 403 Client Error: Forbidden
    "https://ieeexplore.ieee.org/",  # 418 Client Error: I'm a teapot
    "https://pyfits.readthedocs.io/en/v3.2.1/",  # defunct page in CHANGES.rst
    "https://pkgs.dev.azure.com/astropy-project",  # defunct page in CHANGES.rst
    r"https://github\.com/astropy/astropy/(?:issues|pull)/\d+",
]
linkcheck_timeout = 180
linkcheck_anchors = False
linkcheck_report_timeouts_as_broken = True
linkcheck_allow_unauthorized = False


def rstjinja(app, docname, source):
    """Render pages as a jinja template to hide/show dev docs."""
    # Make sure we're outputting HTML
    if app.builder.format != "html":
        return
    files_to_render = ["index_dev", "install"]
    if docname in files_to_render:
        logger.info("Jinja rendering %s", docname)
        rendered = app.builder.templates.render_string(
            source[0], app.config.html_context
        )
        source[0] = rendered


def resolve_astropy_reference(app, env, node, contnode):
    """
    Reference targets for ``astropy:`` are special cases.

    Documentation links in astropy can be set up as intersphinx links so that
    affiliate packages do not have to override the docstrings when building
    the docs.

    """
    # should the node be processed?
    reftarget = node.get("reftarget")  # str or None
    if str(reftarget).startswith("astropy:"):
        # This allows Astropy to use intersphinx links to itself and have
        # them resolve to local links. Downstream packages will see intersphinx.
        # TODO: Remove this when https://github.com/sphinx-doc/sphinx/issues/9169 is implemented upstream.
        process, replace = True, "astropy:"
    else:
        process, replace = False, ""

    # make link local
    if process:
        reftype = node.get("reftype")
        refdoc = node.get("refdoc", app.env.docname)
        # convert astropy intersphinx targets to local links.
        # there are a few types of intersphinx link patterns, as described in
        # https://docs.readthedocs.io/en/stable/guides/intersphinx.html
        reftarget = reftarget.replace(replace, "")
        if reftype == "doc":  # also need to replace the doc link
            node.replace_attr("reftarget", reftarget)
        # Delegate to the ref node's original domain/target (typically :ref:)
        try:
            domain = app.env.domains[node["refdomain"]]
            return domain.resolve_xref(
                app.env, refdoc, app.builder, reftype, reftarget, node, contnode
            )
        except Exception:
            pass

        # Otherwise return None which should delegate to intersphinx


__minimum_python_version__ = pyproject["project"]["requires-python"].replace(">=", "")

min_versions = {}
for line in metadata.requires("astropy"):
    req = Requirement(line.split(";")[0])
    min_versions[req.name.lower()] = str(req.specifier)

# The following global_substitutions can be used throughout the
# documentation via sphinxcontrib-globalsubs. The key to the dictionary
# is the name of the case-sensitive substitution. For example, if the
# key is `"SkyCoord"`, then it can be used as `|SkyCoord|` throughout
# the documentation.

global_substitutions: dict[str, str] = {
    # NumPy
    "ndarray": ":class:`numpy.ndarray`",
    # Coordinates
    "EarthLocation": ":class:`~astropy.coordinates.EarthLocation`",
    "Angle": "`~astropy.coordinates.Angle`",
    "Latitude": "`~astropy.coordinates.Latitude`",
    "Longitude": ":class:`~astropy.coordinates.Longitude`",
    "BaseFrame": "`~astropy.coordinates.BaseCoordinateFrame`",
    "SkyCoord": ":class:`~astropy.coordinates.SkyCoord`",
    "SpectralCoord": "`~astropy.coordinates.SpectralCoord`",
    # Cosmology
    "Cosmology": ":class:`~astropy.cosmology.Cosmology`",
    "Cosmology.read": ":meth:`~astropy.cosmology.Cosmology.read`",
    "Cosmology.write": ":meth:`~astropy.cosmology.Cosmology.write`",
    "Cosmology.from_format": ":meth:`~astropy.cosmology.Cosmology.from_format`",
    "Cosmology.to_format": ":meth:`~astropy.cosmology.Cosmology.to_format`",
    "FLRW": ":class:`~astropy.cosmology.FLRW`",
    "LambdaCDM": ":class:`~astropy.cosmology.LambdaCDM`",
    "FlatLambdaCDM": ":class:`~astropy.cosmology.FlatLambdaCDM`",
    "WMAP1": ":ref:`astropy_cosmology_realizations_WMAP1`",
    "WMAP3": ":ref:`astropy_cosmology_realizations_WMAP3`",
    "WMAP5": ":ref:`astropy_cosmology_realizations_WMAP5`",
    "WMAP7": ":ref:`astropy_cosmology_realizations_WMAP7`",
    "WMAP9": ":ref:`astropy_cosmology_realizations_WMAP9`",
    "Planck13": ":ref:`astropy_cosmology_realizations_Planck13`",
    "Planck15": ":ref:`astropy_cosmology_realizations_Planck15`",
    "Planck18": ":ref:`astropy_cosmology_realizations_Planck18`",
    "FlatCosmologyMixin": ":class:`~astropy.cosmology.FlatCosmologyMixin`",
    "FlatFLRWMixin": ":class:`~astropy.cosmology.FlatFLRWMixin`",
    "default_cosmology": ":class:`~astropy.cosmology.default_cosmology`",
    # SAMP
    "SAMPClient": ":class:`~astropy.samp.SAMPClient`",
    "SAMPIntegratedClient": ":class:`~astropy.samp.SAMPIntegratedClient`",
    "SAMPHubServer": ":class:`~astropy.samp.SAMPHubServer`",
    "SAMPHubProxy": ":class:`~astropy.samp.SAMPHubProxy`",
    # Table
    "Column": ":class:`~astropy.table.Column`",
    "MaskedColumn": ":class:`~astropy.table.MaskedColumn`",
    "TableColumns": ":class:`~astropy.table.TableColumns`",
    "Row": ":class:`~astropy.table.Row`",
    "Table": ":class:`~astropy.table.Table`",
    "QTable": ":class:`~astropy.table.QTable`",
    # Time
    "Time": ":class:`~astropy.time.Time`",
    "TimeDelta": ":class:`~astropy.time.TimeDelta`",
    # Timeseries
    "TimeSeries": ":class:`~astropy.timeseries.TimeSeries`",
    "BinnedTimeSeries": ":class:`~astropy.timeseries.BinnedTimeSeries`",
    # Distribution
    "Distribution": ":class:`~astropy.uncertainty.Distribution`",
    # Units
    "PhysicalType": ":class:`~astropy.units.PhysicalType`",
    "Quantity": ":class:`~astropy.units.Quantity`",
    "Unit": ":class:`~astropy.units.UnitBase`",
    "StructuredUnit": ":class:`~astropy.units.StructuredUnit`",
    # Utils
    "Masked": ":class:`~astropy.utils.masked.Masked`",
    # Minimum versions
    "minimum_python_version": f"{__minimum_python_version__}",
    "minimum_numpy_version": f"{min_versions['numpy']}",
    "minimum_pyerfa_version": f"{min_versions['pyerfa']}",
    "minimum_matplotlib_version": f"{min_versions['matplotlib']}",
    "minimum_scipy_version": f"{min_versions['scipy']}",
    "minimum_asdf_astropy_version": f"{min_versions['asdf-astropy']}",
    "minimum_packaging_version": f"{min_versions['packaging']}",
    "minimum_pyyaml_version": f"{min_versions['pyyaml']}",
    "minimum_ipython_version": f"{min_versions['ipython']}",
    "minimum_pyarrow_version": f"{min_versions['pyarrow']}",
    "minimum_fsspec_version": f"{min_versions['fsspec']}",
    "minimum_s3fs_version": f"{min_versions['s3fs']}",
}
# Because sphinxcontrib-globalsubs does not work for regular reStructuredText
# links, we first define the links and then process them into the form
# of a reStructuredText external link.

links_to_become_substitutions: dict[str, str] = {
    # Python
    "Python": "https://www.python.org",
    "PEP8": "https://www.python.org/dev/peps/pep-0008",
    # Astropy
    "Astropy mailing list": "https://mail.python.org/mailman/listinfo/astropy",
    "astropy-dev mailing list": "http://groups.google.com/group/astropy-dev",
    # NumPy
    "NumPy": "https://numpy.org",
    "numpydoc": "https://pypi.org/project/numpydoc",
    # erfa
    "ERFA": "https://github.com/liberfa/erfa",
    "PyERFA": "http://pyerfa.readthedocs.org",
    # matplotlib
    "Matplotlib": "https://matplotlib.org",
    # sofa
    "SOFA": "http://www.iausofa.org/index.html",
    # scipy
    "SciPy": "https://www.scipy.org",
    # packaging
    "packaging": "https://packaging.pypa.io",
    # IPython
    "IPython": "https://ipython.org",
    # pip
    "pip": "https://pip.pypa.io",
    # pipenv
    "pipenv": "https://pipenv.pypa.io/en/latest",
    # virtualenv
    "virtualenv": "https://pypi.org/project/virtualenv",
    "virtualenvwrapper": "https://pypi.org/project/virtualenvwrapper",
    # conda
    "conda": "https://conda.io/docs",
    "miniconda": "https://docs.conda.io/en/latest/miniconda.html",
    # pytest
    "pytest": "https://pytest.org/en/latest/index.html",
    "pytest-astropy": "https://github.com/astropy/pytest-astropy",
    "pytest-doctestplus": "https://github.com/astropy/pytest-doctestplus",
    "pytest-remotedata": "https://github.com/astropy/pytest-remotedata",
    # fsspec
    "fsspec": "https://filesystem-spec.readthedocs.io",
    # s3fs
    "s3fs": "https://s3fs.readthedocs.io",
    # TOPCAT
    "STIL": "http://www.starlink.ac.uk/stil",
    "STILTS": "http://www.starlink.ac.uk/stilts",
    "TOPCAT": "http://www.starlink.ac.uk/topcat",
    # OpenAstronomy
    "OpenAstronomy Packaging Guide": "https://packaging-guide.openastronomy.org/en/latest",
}

processed_links = {
    key: f"`{key} <{value}>`_" for key, value in links_to_become_substitutions.items()
}

global_substitutions |= processed_links


def setup(app):
    if sphinx_gallery is None:
        logger.warning(
            "The sphinx_gallery extension is not installed, so the "
            "gallery will not be built.  You will probably see "
            "additional warnings about undefined references due "
            "to this."
        )

    # Generate the page from Jinja template
    app.connect("source-read", rstjinja)
    # Set this to higher priority than intersphinx; this way when building
    # docs astropy: targets will go to the local docs instead of the
    # intersphinx mapping
    app.connect("missing-reference", resolve_astropy_reference, priority=400)