| 1 |
# Configuration file for the Sphinx documentation builder. |
| 2 |
# |
| 3 |
# This file does only contain a selection of the most common options. For a |
| 4 |
# full list see the documentation: |
| 5 |
# http://www.sphinx-doc.org/en/master/config |
| 6 |
|
| 7 |
import os |
| 8 |
import datetime |
| 9 |
from pathlib import Path |
| 10 |
|
| 11 |
from sunpy_sphinx_theme import PNG_ICON |
| 12 |
|
| 13 |
from packaging.version import Version |
| 14 |
|
| 15 |
# -- Project information ----------------------------------------------------- |
| 16 |
|
| 17 |
# The full version, including alpha/beta/rc tags |
| 18 |
from drms import __version__ |
| 19 |
|
| 20 |
_version = Version(__version__) |
| 21 |
version = release = str(_version) |
| 22 |
# Avoid "post" appearing in version string in rendered docs |
| 23 |
if _version.is_postrelease: |
| 24 |
version = release = _version.base_version |
| 25 |
# Avoid long githashes in rendered Sphinx docs |
| 26 |
elif _version.is_devrelease: |
| 27 |
version = release = f"{_version.base_version}.dev{_version.dev}" |
| 28 |
is_development = _version.is_devrelease |
| 29 |
is_release = not (_version.is_prerelease or _version.is_devrelease) |
| 30 |
|
| 31 |
project = "drms" |
| 32 |
author = "The SunPy Community" |
| 33 |
copyright = f"{datetime.datetime.now().year}, {author}" # noqa: A001 |
| 34 |
|
| 35 |
# -- General configuration --------------------------------------------------- |
| 36 |
|
| 37 |
# Wrap large function/method signatures |
| 38 |
maximum_signature_line_length = 80 |
| 39 |
|
| 40 |
# Add any Sphinx extension module names here, as strings. They can be |
| 41 |
# extensions coming with Sphinx (named "sphinx.ext.*") or your custom |
| 42 |
# ones. |
| 43 |
extensions = [ |
| 44 |
# TODO: Re-enable this, it was failing the doc build |
| 45 |
# "hoverxref.extension", |
| 46 |
"sphinx_copybutton", |
| 47 |
"sphinx_gallery.gen_gallery", |
| 48 |
"sphinx.ext.autodoc", |
| 49 |
"sphinx.ext.coverage", |
| 50 |
"sphinx.ext.doctest", |
| 51 |
"sphinx.ext.inheritance_diagram", |
| 52 |
"sphinx.ext.intersphinx", |
| 53 |
"sphinx.ext.napoleon", |
| 54 |
"sphinx.ext.todo", |
| 55 |
"sphinx.ext.viewcode", |
| 56 |
"sphinx.ext.mathjax", |
| 57 |
"sphinx_automodapi.automodapi", |
| 58 |
"sphinx_automodapi.smart_resolver", |
| 59 |
"sphinx_changelog", |
| 60 |
] |
| 61 |
|
| 62 |
# Add any paths that contain templates here, relative to this directory. |
| 63 |
# templates_path = ["_templates"] |
| 64 |
|
| 65 |
# List of patterns, relative to source directory, that match files and |
| 66 |
# directories to ignore when looking for source files. |
| 67 |
# This pattern also affects html_static_path and html_extra_path. |
| 68 |
automodapi_toctreedirnm = "generated/api" |
| 69 |
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] |
| 70 |
|
| 71 |
# The suffix(es) of source filenames. |
| 72 |
source_suffix = {".rst": "restructuredtext"} |
| 73 |
|
| 74 |
# The master toctree document. |
| 75 |
master_doc = "index" |
| 76 |
|
| 77 |
# Treat everything in single ` as a Python reference. |
| 78 |
default_role = "py:obj" |
| 79 |
|
| 80 |
# -- Options for intersphinx extension --------------------------------------- |
| 81 |
|
| 82 |
intersphinx_mapping = { |
| 83 |
"python": ( |
| 84 |
"https://docs.python.org/3/", |
| 85 |
(None, "http://www.astropy.org/astropy-data/intersphinx/python3.inv"), |
| 86 |
), |
| 87 |
"numpy": ( |
| 88 |
"https://numpy.org/doc/stable/", |
| 89 |
(None, "http://www.astropy.org/astropy-data/intersphinx/numpy.inv"), |
| 90 |
), |
| 91 |
"scipy": ( |
| 92 |
"https://docs.scipy.org/doc/scipy/reference/", |
| 93 |
(None, "http://www.astropy.org/astropy-data/intersphinx/scipy.inv"), |
| 94 |
), |
| 95 |
"matplotlib": ("https://matplotlib.org/stable", None), |
| 96 |
"astropy": ("https://docs.astropy.org/en/stable/", None), |
| 97 |
"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), |
| 98 |
"sunpy": ("https://docs.sunpy.org/en/stable/", None), |
| 99 |
} |
| 100 |
|
| 101 |
# -- Options for HTML output ------------------------------------------------- |
| 102 |
|
| 103 |
# The theme to use for HTML and HTML Help pages. See the documentation for |
| 104 |
# a list of builtin themes. |
| 105 |
html_theme = "sunpy" |
| 106 |
|
| 107 |
# Render inheritance diagrams in SVG |
| 108 |
graphviz_output_format = "svg" |
| 109 |
|
| 110 |
graphviz_dot_args = [ |
| 111 |
"-Nfontsize=10", |
| 112 |
"-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif", |
| 113 |
"-Efontsize=10", |
| 114 |
"-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif", |
| 115 |
"-Gfontsize=10", |
| 116 |
"-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif", |
| 117 |
] |
| 118 |
|
| 119 |
# Add any paths that contain custom static files (such as style sheets) here, |
| 120 |
# relative to this directory. They are copied after the builtin static files, |
| 121 |
# so a file named "default.css" will overwrite the builtin "default.css". |
| 122 |
# html_static_path = ["_static"] |
| 123 |
|
| 124 |
# By default, when rendering docstrings for classes, sphinx.ext.autodoc will |
| 125 |
# make docs with the class-level docstring and the class-method docstrings, |
| 126 |
# but not the __init__ docstring, which often contains the parameters to |
| 127 |
# class constructors across the scientific Python ecosystem. The option below |
| 128 |
# will append the __init__ docstring to the class-level docstring when rendering |
| 129 |
# the docs. For more options, see: |
| 130 |
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content |
| 131 |
autoclass_content = "both" |
| 132 |
|
| 133 |
# -- Other options ---------------------------------------------------------- |
| 134 |
|
| 135 |
# JSOC email os env |
| 136 |
# see https://github.com/sunpy/sunpy/wiki/Home:-JSOC |
| 137 |
os.environ["JSOC_EMAIL"] = "[email protected]" |
| 138 |
|
| 139 |
# -- Options for hoverxref ----------------------------------------------------- |
| 140 |
|
| 141 |
if os.environ.get("READTHEDOCS"): |
| 142 |
hoverxref_api_host = "https://readthedocs.org" |
| 143 |
if os.environ.get("PROXIED_API_ENDPOINT"): |
| 144 |
# Use the proxied API endpoint |
| 145 |
# - A RTD thing to avoid a CSRF block when docs are using a |
| 146 |
# custom domain |
| 147 |
hoverxref_api_host = "/_" |
| 148 |
|
| 149 |
hoverxref_tooltip_maxwidth = 600 # RTD main window is 696px |
| 150 |
hoverxref_auto_ref = True |
| 151 |
hoverxref_mathjax = True |
| 152 |
hoverxref_domains = ["py"] |
| 153 |
hoverxref_role_types = { |
| 154 |
# roles with py domain |
| 155 |
"attr": "tooltip", |
| 156 |
"class": "tooltip", |
| 157 |
"const": "tooltip", |
| 158 |
"data": "tooltip", |
| 159 |
"exc": "tooltip", |
| 160 |
"func": "tooltip", |
| 161 |
"meth": "tooltip", |
| 162 |
"mod": "tooltip", |
| 163 |
"obj": "tooltip", |
| 164 |
# roles with std domain |
| 165 |
"confval": "tooltip", |
| 166 |
"hoverxref": "tooltip", |
| 167 |
"ref": "tooltip", |
| 168 |
"term": "tooltip", |
| 169 |
} |
| 170 |
|
| 171 |
# -- Options for sphinx-copybutton --------------------------------------------- |
| 172 |
|
| 173 |
# Python Repl + continuation, Bash, ipython and qtconsole + continuation, jupyter-console + continuation |
| 174 |
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " |
| 175 |
copybutton_prompt_is_regexp = True |
| 176 |
|
| 177 |
# -- Sphinx Gallery ------------------------------------------------------------ |
| 178 |
|
| 179 |
sphinx_gallery_conf = { |
| 180 |
"backreferences_dir": Path("generated") / "modules", |
| 181 |
"filename_pattern": "^((?!skip_).)*$", |
| 182 |
"examples_dirs": Path("..") / "examples", |
| 183 |
"within_subsection_order": "ExampleTitleSortKey", |
| 184 |
"gallery_dirs": Path("generated") / "gallery", |
| 185 |
"default_thumb_file": PNG_ICON, |
| 186 |
"abort_on_example_error": False, |
| 187 |
"plot_gallery": "True", |
| 188 |
"remove_config_comments": True, |
| 189 |
"doc_module": ("sunpy"), |
| 190 |
"only_warn_on_example_error": True, |
| 191 |
"matplotlib_animations": True, |
| 192 |
} |