Merge pull request #3281 from dcamron/docs-show-source

DOC: Theme fixes, source links, and calendar

docs/_static/theme-unidata.css

@@ -1,5 +1,5 @@
 /* Define "Unidata Blue" RGB values */
-:root {
+html {
     --unidata-blue-rgb: 6, 119, 143;
 }
 
@@ -19,10 +19,19 @@
 
 .bd-header .navbar-nav>.nav-item>.nav-link, 
 .bd-header .dropdown-toggle,
-.bd-header .fa-solid {
+.bd-header .fa-solid,
+.bd-header .btn {
     color: #fff !important;
  }
 
+.version-switcher__button {
+    border-color: #fff !important;
+}
+
+.search-button {
+    padding: 0 0 0;
+}
+
 .navbar-nav .dropdown-menu {
     background-color: var(--pst-color-background);
 }

docs/conf.py

@@ -10,6 +10,7 @@
 # serve to show the default.
 
 from datetime import datetime
+import inspect
 import os
 from pathlib import Path
 import re
@@ -37,9 +38,9 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.coverage',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.linkcode',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
-    'sphinx.ext.viewcode',
     'sphinx_design',
     'sphinx_gallery.gen_gallery',
     'matplotlib.sphinxext.plot_directive',
@@ -138,8 +139,8 @@
 
 # noinspection PyShadowingBuiltins
 copyright = (
-    f'2008\u2013{cur_date:%Y}, MetPy Developers.'
-    'Development is supported by Unidata and the National Science Foundation.'
+    f'2008\u2013{cur_date:%Y}, MetPy Developers. '
+    'Development is supported by Unidata and the National Science Foundation'
 )
 
 # The version info for the project you're documenting, acts as replacement for
@@ -213,13 +214,19 @@
         {
             'name': 'GitHub',
             'url': 'https://github.com/Unidata/MetPy',
-            'icon': 'fa-brands fa-github-square',
+            'icon': 'fa-brands fa-github',
             'type': 'fontawesome',
         },
         {
             'name': 'Twitter',
             'url': 'https://twitter.com/MetPy',
-            'icon': 'fa-brands fa-twitter-square',
+            'icon': 'fa-brands fa-twitter',
+            'type': 'fontawesome',
+        },
+        {
+            'name': 'Calendar',
+            'url': 'https://calendar.google.com/calendar/embed?src=c_596cc34cd7196caec223786795c8730786aead6e2dbffe03403186f203075973%40group.calendar.google.com&ctz=America%2FDenver',
+            'icon': 'fa-solid fa-calendar',
             'type': 'fontawesome',
         }
     ],
@@ -316,7 +323,7 @@
 # html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 # html_show_sphinx = True
@@ -452,3 +459,61 @@
     r'https://docs.github.com/': {'User-Agent': 'Mozilla/5.0 (X11; Ubuntu; Linux i686; '
                                                 'rv:24.0) Gecko/20100101 Firefox/24.0'}
 }
+
+# Function to resolve source code links for `linkcode`
+# adapted from NumPy, Pandas implementations
+def linkcode_resolve(domain, info):
+    """
+    Determine the URL corresponding to Python object
+    """
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    try:
+        fn = inspect.getsourcefile(inspect.unwrap(obj))
+    except TypeError:
+        try:  # property
+            fn = inspect.getsourcefile(inspect.unwrap(obj.fget))
+        except (AttributeError, TypeError):
+            fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except TypeError:
+        try:  # property
+            source, lineno = inspect.getsourcelines(obj.fget)
+        except (AttributeError, TypeError):
+            lineno = None
+    except OSError:
+        lineno = None
+
+    if lineno:
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
+    else:
+        linespec = ""
+
+    fn = os.path.relpath(fn, start=os.path.dirname(metpy.__file__))
+
+    if "+" in metpy.__version__:
+        return f"https://github.com/Unidata/MetPy/blob/main/src/metpy/{fn}{linespec}"
+    else:
+        return (
+            f"https://github.com/Unidata/MetPy/blob/"
+            f"v{metpy.__version__}/src/metpy/{fn}{linespec}"
+        )

docs/index.rst

@@ -19,7 +19,6 @@ with weather data. MetPy supports Python >= 3.9 and is freely available under a
 
 If you're new to MetPy, check out our :doc:`Getting Started <userguide/startingguide>` guide.
 
-
 .. grid:: 1 2 2 2
     :gutter: 2
 
@@ -68,8 +67,21 @@ If you're new to MetPy, check out our :doc:`Getting Started <userguide/startingg
         Check out MetPy's gallery of examples which contains
         sample code demonstrating various parts of MetPy's functionality.
 
+Calendar
+--------
+Check out the MetPy Community Calendar below. The bi-weekly MetPy Community Dev Call
+is an open discussion for community input, developer highlights and updates, and
+community code showcase opportunities. Stop by!
+Find more information in the pinned thread in the
+`Announcements section <https://github.com/Unidata/MetPy/discussions/categories/announcements>`
+of MetPy GitHub Discussions.
+
+.. raw:: html
+
+    <iframe src="https://calendar.google.com/calendar/embed?height=600&wkst=1&bgcolor=%23ffffff&ctz=America%2FDenver&title=MetPy%20Community%20Calendar&showPrint=0&showTabs=0&showCalendars=0&showTz=1&src=Y181OTZjYzM0Y2Q3MTk2Y2FlYzIyMzc4Njc5NWM4NzMwNzg2YWVhZDZlMmRiZmZlMDM0MDMxODZmMjAzMDc1OTczQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20&color=%23D50000" style="border-width:0" width="800" height="600" frameborder="0" scrolling="no"></iframe>
 
-Our up-to-date references for grants and funding can be found `here <https://github.com/Unidata/MetPy/blob/main/CITATION.cff>`_.
+Our up-to-date references for grants and funding can be found
+`here <https://github.com/Unidata/MetPy/blob/main/CITATION.cff>`_.
 
 .. image:: _static/NSF.jpg
    :width: 100 px

docs/userguide/index.rst

@@ -129,8 +129,8 @@ Bulletin of the American Meteorological Society.
     from metpy.cbook import get_test_data
     import metpy.plots as mpplots
 
-    data = pd.read_csv(get_test_data('SFC_obs.csv', as_file_obj=False),
-                       infer_datetime_format=True, parse_dates=['valid'])
+    data = pd.read_csv(get_test_data('SFC_obs.csv', as_file_obj=False))
+    data['valid'] = pd.to_datetime(data['valid'], format='%Y-%m-%d %H:%M:%S')
 
     obs = mpplots.PlotObs()
     obs.data = data

examples/plots/surface_declarative.py

@@ -27,8 +27,8 @@
 # Python script. The data are pre-processed to determine sky cover and weather symbols from
 # text output.
 
-data = pd.read_csv(get_test_data('SFC_obs.csv', as_file_obj=False),
-                   infer_datetime_format=True, parse_dates=['valid'])
+data = pd.read_csv(get_test_data('SFC_obs.csv', as_file_obj=False))
+data['valid'] = pd.to_datetime(data['valid'], format='%Y-%m-%d %H:%M:%S')
 
 ########################################
 # **Plotting the data**

src/metpy/units.py

@@ -25,6 +25,10 @@
 import numpy as np
 import pint
 
+from .package_tools import Exporter
+
+exporter = Exporter(globals())
+
 log = logging.getLogger(__name__)
 
 UndefinedUnitError = pint.UndefinedUnitError
@@ -55,6 +59,7 @@ def _fix_udunits_div(string):
                        _fix_udunits_div]
 
 
+@exporter.export
 def setup_registry(reg):
     """Set up a given registry with MetPy's default tweaks and settings."""
     reg.autoconvert_offset_to_baseunit = True
@@ -95,6 +100,7 @@ def setup_registry(reg):
 warnings.simplefilter('ignore', category=pint.UnitStrippedWarning)
 
 
+@exporter.export
 def pandas_dataframe_to_unit_arrays(df, column_units=None):
     """Attach units to data in pandas dataframes and return quantities.