+
+This theme uses shadows to convey depth in the light theme mode and opacity in the dark one.
+It defines 4 color variables that help build overlays in your documentation.
+
+- :code:`background`: color of the back-most surface of the documentation
+- :code:`on-background` elements that are set on top of this background (e.g. the header navbar on dark mode).
+- :code:`surface` elements set on the background with a light-grey color in the light theme mode. This color has been kept in the dark theme (e.g. code-block directives).
+- :code:`on-surface` elements that are on top of :code:`surface` elements (e.g. sidebar directives).
+
+The following image should help you understand these overlays:
+
+.. raw:: html
+
+
+
+
+
+
background
+
+
+
on-background
+
+
+
surface
+
+
+
on-surface
+
+
+
+Snippets
+--------
+
+Documentation :any:`index ` and :any:`Module ` index.
+
+Some code:
+
+.. code-block:: python
+
+ """
+ Parameters
+ ----------
+ x : `type`
+ Description of parameter x.
+ """
+ import numpy as np
+
+ def func(x):
+ return np.mean(x)
+
+ # This is a comment
+ return func
+
+It's good to have your upstream remote have a scary name [#]_, to remind you that it's a read-write remote:
+
+.. code-block:: bash
+
+ $ git remote add upstream-rw git@github.com:sunpy/sunpy.git
+ $ git fetch upstream-rw
+
+.. [#] Text of the first footnote.
+
+``:func:``
+:func:`numpy.mean`
+
+``:meth:``
+:meth:`numpy.mean`
+
+``:class:``
+:class:`numpy.mean`
+
+Normal
+`numpy.mean`
+
+``:func:``
+:func:`numpy.ndarray.mean`
+
+``:meth:``
+:meth:`numpy.ndarray.mean`
+
+``:class:``
+:class:`numpy.ndarray.mean`
+
+Normal
+`numpy.ndarray.mean`
+
+Sometimes you need a URL: `bbc.com `__
+
+Contributing to ``sunraster``
diff --git a/docs/conf.py b/docs/conf.py
index d00eca1b1..3afb45c32 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,15 +1,126 @@
-# -- Project information -----------------------------------------------------
-from datetime import datetime
+"""
+Configuration file for the Sphinx documentation builder.
+"""
+import os
+import sys
+import datetime
+from pathlib import Path
-project = "sunpy-sphinx-theme"
-copyright = f"{datetime.now().year}, The SunPy Project"
-author = "The SunPy Project"
-release = "2.0"
+from sphinx_gallery.sorting import ExampleTitleSortKey, ExplicitOrder
-# -- General configuration ---------------------------------------------------
-extensions = []
-templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+from sunpy_sphinx_theme import SVG_ICON
+
+project = "Test Package"
+author = "The Test Package Community"
+copyright = f"{datetime.datetime.now().year}, {author}"
+extensions = [
+ "sphinx_automodapi.automodapi",
+ "sphinx_automodapi.smart_resolver",
+ "hoverxref.extension",
+ "matplotlib.sphinxext.plot_directive",
+ "sphinx_copybutton",
+ "sphinx_design",
+ "sphinx_gallery.gen_gallery",
+ "sphinx_togglebutton",
+ "sphinx.ext.coverage",
+ "sphinx.ext.doctest",
+ "sphinx.ext.inheritance_diagram",
+ "sphinx.ext.intersphinx",
+ "sphinx.ext.mathjax",
+ "sphinx.ext.napoleon",
+ "sphinx.ext.todo",
+ "sphinx.ext.viewcode",
+]
+
+# Add the test package to the path so we can import it for automodapi
+sys.path.append(Path(".").absolute().as_posix())
+import test_package # NOQA - Test package must be on the path
-# -- Options for HTML output -------------------------------------------------
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+source_suffix = ".rst"
+master_doc = "index"
+default_role = "obj"
+napoleon_use_rtype = False
+intersphinx_mapping = {
+ "python": (
+ "https://docs.python.org/3/",
+ (None, "http://www.astropy.org/astropy-data/intersphinx/python3.inv"),
+ ),
+ "numpy": (
+ "https://numpy.org/doc/stable/",
+ (None, "http://www.astropy.org/astropy-data/intersphinx/numpy.inv"),
+ ),
+ "scipy": (
+ "https://docs.scipy.org/doc/scipy/reference/",
+ (None, "http://www.astropy.org/astropy-data/intersphinx/scipy.inv"),
+ ),
+ "matplotlib": (
+ "https://matplotlib.org/",
+ (None, "http://www.astropy.org/astropy-data/intersphinx/matplotlib.inv"),
+ ),
+ "astropy": ("https://docs.astropy.org/en/stable/", None),
+ "sqlalchemy": ("https://docs.sqlalchemy.org/en/latest/", None),
+ "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+ "skimage": ("https://scikit-image.org/docs/stable/", None),
+ "drms": ("https://docs.sunpy.org/projects/drms/en/stable/", None),
+ "parfive": ("https://parfive.readthedocs.io/en/latest/", None),
+ "reproject": ("https://reproject.readthedocs.io/en/stable/", None),
+}
html_theme = "sunpy"
+graphviz_output_format = "svg"
+graphviz_dot_args = [
+ "-Nfontsize=10",
+ "-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+ "-Efontsize=10",
+ "-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+ "-Gfontsize=10",
+ "-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+]
+sphinx_gallery_conf = {
+ "filename_pattern": "^((?!skip_).)*$",
+ "examples_dirs": os.path.join("..", "examples"),
+ "subsection_order": ExplicitOrder(
+ [
+ "../examples/section",
+ ]
+ ),
+ "within_subsection_order": ExampleTitleSortKey,
+ "gallery_dirs": os.path.join("generated", "gallery"),
+ "default_thumb_file": SVG_ICON,
+ "abort_on_example_error": False,
+ "plot_gallery": "True",
+ "remove_config_comments": True,
+}
+if os.environ.get("READTHEDOCS"):
+ hoverxref_api_host = "https://readthedocs.org"
+
+ if os.environ.get("PROXIED_API_ENDPOINT"):
+ # Use the proxied API endpoint
+ # A RTD thing to avoid a CSRF block when docs are using a custom domain
+ hoverxref_api_host = "/_"
+
+hoverxref_auto_ref = False
+hoverxref_domains = ["py"]
+hoverxref_mathjax = True
+hoverxref_modal_hover_delay = 500
+hoverxref_tooltip_maxwidth = 600 # RTD main window is 696px
+hoverxref_intersphinx = list(intersphinx_mapping.keys())
+hoverxref_role_types = {
+ # Roles within the py domain
+ "attr": "tooltip",
+ "class": "tooltip",
+ "const": "tooltip",
+ "data": "tooltip",
+ "exc": "tooltip",
+ "func": "tooltip",
+ "meth": "tooltip",
+ "mod": "tooltip",
+ "obj": "tooltip",
+ # Roles within the std domain
+ "confval": "tooltip",
+ "hoverxref": "tooltip",
+ "ref": "tooltip", # Would be used by hoverxref_auto_ref if we set it to True
+ "term": "tooltip",
+}
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
diff --git a/docs/customizing.rst b/docs/customizing.rst
index 33a769236..b416d293b 100644
--- a/docs/customizing.rst
+++ b/docs/customizing.rst
@@ -50,7 +50,6 @@ It's possible to add dropdown menus to the topnav by setting document equal to a
Footer links are a number of links which will get placed in the center of the footer.
They are specified in the same format as the ``navbar_links``.
-
Adjusting the Styling
---------------------
@@ -71,6 +70,5 @@ We have tried to use CSS variables to control the styling the key variables are:
--sst-header-text: var(--sst-lighter-color);
--sst-sidebar-background-color: var(--pst-color-background);
-
The included CSS uses "light" (light, lighter, lightest) colors for the background on the light theme and "dark" colors for the text, and the inverse on the dark theme.
The bright accent color is used for some text (e.g. links) on the dark theme, and the muted variant on the light theme to increase contrast.
diff --git a/docs/index.rst b/docs/index.rst
index b492ced7c..1e5f11fc6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,7 +16,44 @@ The core changes between this theme and the `pydata-sphinx-theme` are:
* Add a center element to the footer bar.
* Restyled the theme for SunPy colors.
-.. toctree::
- :maxdepth: 2
+.. grid:: 1 2 2 2
+ :gutter: 3
- customizing
+ .. grid-item-card::
+ :class-card: card
+
+ Documentation
+ ^^^^^^^^^^^^^
+
+ .. toctree::
+ :maxdepth: 1
+
+ customizing
+ colors
+ web-components
+
+ .. grid-item-card::
+ :class-card: card
+
+ Examples
+ ^^^^^^^^
+
+ .. toctree::
+ :maxdepth: 1
+
+ generated/gallery/index
+ code_ref/index
+
+ .. grid-item-card::
+ :class-card: card
+ :link: subsections
+ :link-type: ref
+
+ Conventions
+ ^^^^^^^^^^^
+
+ .. toctree::
+ :maxdepth: 1
+
+ subsections
+ subsections_toc
diff --git a/test_package/docs/subsections.rst b/docs/subsections.rst
similarity index 72%
rename from test_package/docs/subsections.rst
rename to docs/subsections.rst
index 05bc68871..b43663eea 100644
--- a/test_package/docs/subsections.rst
+++ b/docs/subsections.rst
@@ -9,7 +9,7 @@ subsections
Abcdefghijklmnopqrstuvwxyz
**************************
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed congue ligula in erat pulvinar, convallis consectetur mi eleifend. Fusce tincidunt mauris ac lacus mollis, semper bibendum orci semper. Vivamus elit purus, congue ac erat sit amet, iaculis malesuada velit. Nam egestas imperdiet ex. Duis eget dignissim purus. In sollicitudin nibh vel lorem sodales mattis. Nullam vitae leo sed elit consequat aliquam vitae eget diam. Nunc elit justo, consectetur sit amet pulvinar at, imperdiet at felis. Nam dolor dui, sodales in volutpat quis, laoreet vitae enim. Curabitur scelerisque auctor nunc a auctor.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed congue ligula in erat pulvinar, convallis consectetur mi eleifend. Fusce tincidunt mauris ac lacus mollis, semper bibendum orci semper. Vivamus elit purus, congue ac erat sit amet, iaculis malesuada velit. Name egestas imperdiet ex. Duis eget dignissim purus. In sollicitudin nibh vel lorem sodales mattis. Nullam vitae leo sed elit consequat aliquam vitae eget diam. Nunc elit justo, consectetur sit amet pulvinar at, imperdiet at felis. Name dolor dui, sodales in volutpat quis, laoreet vitae enim. Curabitur scelerisque auctor nunc a auctor.
Bcdefghijklmnopqrstuvwxyz
=========================
@@ -32,4 +32,4 @@ Vestibulum est ex, gravida sit amet tortor non, aliquet auctor ante. Nulla conva
Fghijklmnopqrstuvwxyz
"""""""""""""""""""""
-Proin non suscipit massa. Vivamus at auctor felis, ut placerat velit. Mauris sapien turpis, luctus at justo eget, aliquet molestie nisl. Nam molestie eros sem, at commodo ligula pellentesque eu. Vivamus tincidunt a nulla id rhoncus. Integer viverra ipsum arcu, sit amet molestie diam suscipit at. Ut feugiat arcu nisl, eu blandit ipsum vulputate vitae. Mauris orci magna, vulputate sed blandit a, varius quis mi. Vivamus vehicula libero nec erat varius porta. Morbi eros leo, efficitur eu risus et, eleifend ultrices tellus. Fusce nec laoreet eros. In non pulvinar massa. Sed hendrerit posuere massa eu gravida.
+Proin non suscipit massa. Vivamus at auctor felis, ut placerat velit. Mauris sapien turpis, luctus at justo eget, aliquet molestie nisl. Name molestie eros sem, at commodo ligula pellentesque eu. Vivamus tincidunt a nulla id rhoncus. Integer viverra ipsum arcu, sit amet molestie diam suscipit at. Ut feugiat arcu nisl, eu blandit ipsum vulputate vitae. Mauris orci magna, vulputate sed blandit a, various quis mi. Vivamus vehicula libero nec erat various porta. Morbi eros leo, efficitur eu risus et, eleifend ultrices tellus. Fusce nec laoreet eros. In non pulvinar massa. Sed hendrerit posuere massa eu gravida.
diff --git a/test_package/docs/subsections_toc.rst b/docs/subsections_toc.rst
similarity index 73%
rename from test_package/docs/subsections_toc.rst
rename to docs/subsections_toc.rst
index 3356ec854..3b18356b0 100644
--- a/test_package/docs/subsections_toc.rst
+++ b/docs/subsections_toc.rst
@@ -12,7 +12,7 @@ This time, we have a toctree in side the doc with a depth of 5, the goal is to s
Abcdefghijklmnopqrstuvwxyz
**************************
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed congue ligula in erat pulvinar, convallis consectetur mi eleifend. Fusce tincidunt mauris ac lacus mollis, semper bibendum orci semper. Vivamus elit purus, congue ac erat sit amet, iaculis malesuada velit. Nam egestas imperdiet ex. Duis eget dignissim purus. In sollicitudin nibh vel lorem sodales mattis. Nullam vitae leo sed elit consequat aliquam vitae eget diam. Nunc elit justo, consectetur sit amet pulvinar at, imperdiet at felis. Nam dolor dui, sodales in volutpat quis, laoreet vitae enim. Curabitur scelerisque auctor nunc a auctor.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed congue ligula in erat pulvinar, convallis consectetur mi eleifend. Fusce tincidunt mauris ac lacus mollis, semper bibendum orci semper. Vivamus elit purus, congue ac erat sit amet, iaculis malesuada velit. Name egestas imperdiet ex. Duis eget dignissim purus. In sollicitudin nibh vel lorem sodales mattis. Nullam vitae leo sed elit consequat aliquam vitae eget diam. Nunc elit justo, consectetur sit amet pulvinar at, imperdiet at felis. Name dolor dui, sodales in volutpat quis, laoreet vitae enim. Curabitur scelerisque auctor nunc a auctor.
Bcdefghijklmnopqrstuvwxyz
=========================
@@ -35,4 +35,4 @@ Vestibulum est ex, gravida sit amet tortor non, aliquet auctor ante. Nulla conva
Fghijklmnopqrstuvwxyz
"""""""""""""""""""""
-Proin non suscipit massa. Vivamus at auctor felis, ut placerat velit. Mauris sapien turpis, luctus at justo eget, aliquet molestie nisl. Nam molestie eros sem, at commodo ligula pellentesque eu. Vivamus tincidunt a nulla id rhoncus. Integer viverra ipsum arcu, sit amet molestie diam suscipit at. Ut feugiat arcu nisl, eu blandit ipsum vulputate vitae. Mauris orci magna, vulputate sed blandit a, varius quis mi. Vivamus vehicula libero nec erat varius porta. Morbi eros leo, efficitur eu risus et, eleifend ultrices tellus. Fusce nec laoreet eros. In non pulvinar massa. Sed hendrerit posuere massa eu gravida.
+Proin non suscipit massa. Vivamus at auctor felis, ut placerat velit. Mauris sapien turpis, luctus at justo eget, aliquet molestie nisl. Name molestie eros sem, at commodo ligula pellentesque eu. Vivamus tincidunt a nulla id rhoncus. Integer viverra ipsum arcu, sit amet molestie diam suscipit at. Ut feugiat arcu nisl, eu blandit ipsum vulputate vitae. Mauris orci magna, vulputate sed blandit a, various quis mi. Vivamus vehicula libero nec erat various porta. Morbi eros leo, efficitur eu risus et, eleifend ultrices tellus. Fusce nec laoreet eros. In non pulvinar massa. Sed hendrerit posuere massa eu gravida.
diff --git a/docs/test_package/__init__.py b/docs/test_package/__init__.py
new file mode 100644
index 000000000..757c867b1
--- /dev/null
+++ b/docs/test_package/__init__.py
@@ -0,0 +1,2 @@
+from .animals import * # NOQA: F401, F403
+from .timerange import * # NOQA: F401, F403
diff --git a/test_package/test_package/__init__.py b/docs/test_package/animals.py
similarity index 98%
rename from test_package/test_package/__init__.py
rename to docs/test_package/animals.py
index 5225eda08..3d0311198 100644
--- a/test_package/test_package/__init__.py
+++ b/docs/test_package/animals.py
@@ -1,5 +1,5 @@
"""
-This module provies a collection of functions.
+This module provides a collection of functions.
"""
from sunpy.util.decorators import deprecated
diff --git a/test_package/test_package/timerange.py b/docs/test_package/timerange.py
similarity index 98%
rename from test_package/test_package/timerange.py
rename to docs/test_package/timerange.py
index f67f29d67..02c2eabab 100644
--- a/test_package/test_package/timerange.py
+++ b/docs/test_package/timerange.py
@@ -1,5 +1,5 @@
"""
-This module provies a object that can handle a time range.
+This module provides a object that can handle a time range.
"""
from datetime import timedelta
@@ -22,8 +22,8 @@ class TimeRange:
.. note::
- Regardless of how a `sunpy.time.TimeRange` is constructed it will always
- provide a positive time range where the start time is before the end time.
+ Regardless of how a `sunpy.time.TimeRange` is constructed it will always
+ provide a positive time range where the start time is before the end time.
Parameters
----------
diff --git a/docs/web-components.rst b/docs/web-components.rst
new file mode 100644
index 000000000..16e0f19e9
--- /dev/null
+++ b/docs/web-components.rst
@@ -0,0 +1,260 @@
+.. INSPIRED FROM sphinx-design documentation
+.. COPY FROM PYDATA THEME DOCS
+
+========================
+Sphinx Design Components
+========================
+
+The PyData Sphinx Theme uses `sphinx-design `__
+to add several UI components and provide extra flexibility for content creation.
+These include badges, buttons, cards, and tabs, among other components.
+This theme provides custom CSS to ensure that `sphinx-design `__ elements look and feel consistent with this theme.
+
+.. seealso::
+
+ For more information about how to use these extensions, see `the sphinx-design documentation `_.
+
+Below you can find some examples of the components created with the :code:`sphinx-design` extension.
+
+.. _badges-buttons:
+
+Badges and button-links
+=======================
+
+Here are some of the available badges:
+
+:bdg-primary:`primary`
+:bdg-secondary:`secondary`
+:bdg-success:`success`
+:bdg-primary-line:`primary outline`
+:bdg-secondary-line:`secondary outline`
+:bdg-success-line:`success outline`
+
+Here are some of the available button-style links, also using semantic colors:
+
+.. grid:: auto
+
+ .. grid-item::
+
+ .. button-ref:: badges-buttons
+ :ref-type: ref
+ :color: info
+ :shadow:
+
+ Info
+
+ .. grid-item::
+
+ .. button-ref:: badges-buttons
+ :ref-type: ref
+ :color: success
+ :shadow:
+
+ Success
+
+ .. grid-item::
+
+ .. button-ref:: badges-buttons
+ :ref-type: ref
+ :color: warning
+ :shadow:
+
+ Warning
+
+ .. grid-item::
+
+ .. button-ref:: badges-buttons
+ :ref-type: ref
+ :color: danger
+ :shadow:
+
+ Danger
+
+ .. grid-item::
+
+ .. button-ref:: badges-buttons
+ :ref-type: ref
+ :color: muted
+ :shadow:
+
+ Muted
+
+ .. grid-item::
+
+ .. button-ref:: badges-buttons
+ :ref-type: ref
+ :color: light
+ :shadow:
+
+ Light
+
+ .. grid-item::
+
+ .. button-ref:: badges-buttons
+ :ref-type: ref
+ :color: dark
+ :shadow:
+
+ Dark
+
+.. note::
+
+ `Sphinx Design buttons
+ `__
+ are actually links, meaning they are rendered in HTML with ```` tags
+ instead of ``