Debian Codegraph @

docs/conf.py

raw
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 }