feat: add intersphinx and autolink :)

Author: lwasser

_static/css/styles.css

@@ -1,4 +1,9 @@
 
 .navbar-header-items .navbar-header-items__center {
 	margin-left: 2em !important;
+}
+
+.sphinx-codeautolink-a:link {
+	text-decoration: underline;
+	text-decoration-style: dotted;
 }

clean-modular-code/activity-1/clean-code-activity-1.md

@@ -186,7 +186,7 @@ df_combined.shape
 
 ```{dropdown} Hint 1 - built-in help
 If you want to look up a pandas function to get help, Jupyter Lab has built-in help.
-Enter `help(pd.DataFrame.iterrows)`.
+Enter `help(pd.DataFrame.iterrows)` to see the {meth}`documentation <pandas.DataFrame.iterrows>`.
 ```
 
 ```{dropdown} Hint 2 - itterows and at

clean-modular-code/activity-3/clean-code-activity-3.md

@@ -160,9 +160,9 @@ all_papers_df = pd.concat(all_papers_list, axis=0, ignore_index=True)
 
 ## Activity 3, part 2: Add checks to the `format_date` function
 
-The code below creates a `pd.DataFrame` with the first 15 publications in the JOSS sample `data.json` file. This is the first of 3 files you must process in your workflow.
+The code below creates a {class}`pandas.DataFrame` with the first 15 publications in the JOSS sample `data.json` file. This is the first of 3 files you must process in your workflow.
 
-Your first task is to process and format the `published_date` column in the data to make it a `pandas.datetime` object. Having a date in a `datetime` format will allow you to do time-related analysis on your data, such as counting publications by month and year! The expected CrossRef published date should be:
+Your first task is to process and format the `published_date` column in the data to make it a {class}`pandas.Timestamp` object. Having a date in a `datetime` format like {class}`pandas.Timestamp` or {class}`datetime.datetime` will allow you to do time-related analysis on your data, such as counting publications by month and year! The expected CrossRef published date should be:
 
 ```json
 "published": {
@@ -195,7 +195,7 @@ In small groups, do the following:
 
 +++ {"editable": true, "slideshow": {"slide_type": ""}, "tags": ["hide-output", "hide-cell"]}
 
-###  Format dates with `pandas.datetime`
+###  Format dates with {func}`pandas.to_datetime`
 
 Let's work on formatting dates so there is a consistent format in our dataframe. Python has a [string formatting language](https://docs.python.org/3/library/string.html#formatspec) that defines useful characters for formatting.
 
@@ -362,13 +362,13 @@ format_date(joss_pubs_df["published_date"][13])
 
 +++ {"editable": true, "slideshow": {"slide_type": ""}}
 
-### How to apply functions to DataFrame values: `pandas.apply()` 
+### How to apply functions to DataFrame values: `.apply()` 
 
-The `pandas.apply()` method allows you to apply any function to rows or columns in a `pandas.DataFrame`. For example, you can use it to perform operations on specific column or row values. When you use `.apply()`, you can specify whether you want to apply the function across columns `(axis=0)` (the default) or across rows `(axis=1)`. 
+The {meth}`.apply() <pandas.DataFrame.apply>` method allows you to apply any function to rows or columns in a {class}`pandas.DataFrame`. For example, you can use it to perform operations on specific column or row values. When you use `.apply()`, you can specify whether you want to apply the function across columns `(axis=0)` (the default) or across rows `(axis=1)`. 
 
 For example, if you want to apply a function to each row of a DataFrame, you would use `df.apply(your_function, axis=1)`. This function is especially useful for applying logic that can’t be easily achieved with built-in pandas functions, allowing for more flexibility in data processing.
 
-You can use `.apply` in pandas to efficiently replace `for loops` to process row and column values in a `pandas.DataFrame`.
+You can use `.apply` in pandas to efficiently replace `for loops` to process row and column values in a {class}`pandas.DataFrame`.
 
 ```python
 # Apply the format_date function to every row in the published_date column

clean-modular-code/python-dry-modular-code.md

@@ -92,7 +92,7 @@ For example,`print()` is a function used to write output to the Python console (
 Below, you will see the function that you looked at in the previous lesson. This is a custom function with a custom name.
 
 ```python
-def convert_to_kelvin(temperature_fahr) 
+def convert_to_kelvin(temperature_fahr):
     """Convert temperature in Fahrenheit to kelvin.
 
     Parameters:

clean-modular-code/python-pep-8.md

@@ -325,7 +325,7 @@ Most text editors allow you to set up guides to see how long your code is. You c
 * PEP 8 recommends organizing imports in the following order:
 
 1. **Standard Library Imports**: These built-in modules come with Python, such as `os` and `glob`. You can find the full list [here](https://docs.python.org/3/library/index.html).
-2. **Third-Party Imports**: Libraries that you install via `pip`, like `numpy` and `pandas`.
+2. **Third-Party Imports**: Libraries that you install via `pip`, like {mod}`numpy` and {mod}`pandas`.
 3. **Local Imports**: Code or modules specific to your project.
 
 Here’s an example following PEP 8 conventions:

code-workflow-logic/about-python-functions.md

@@ -71,9 +71,9 @@ Source: Francois Michonneau.
 
 A well-defined function only does one thing but does it well and often in various contexts. Often, the operations in a good function are useful for many tasks.
 
-Take, for instance, the **numpy** function called `mean()`, which computes mean values from a **numpy** array.
+Take, for instance, the **{mod}`numpy`** function called {func}`~numpy.mean`, which computes mean values from a **numpy** array.
 
-This function only does one thing-- it computes a mean. However, you may use the `np.mean()` function many times in your code on multiple **numpy** arrays because it has been defined to take any **numpy** array as an input.
+This function only does one thing-- it computes a mean. However, you may use the {func}`np.mean() <numpy.mean>` function many times in your code on multiple **numpy** arrays because it has been defined to take any **numpy** array as an input.
 
 For example:
 <!-- #endregion -->
@@ -88,7 +88,7 @@ np.mean(arr)
 ```
 
 <!-- #region editable=true slideshow={"slide_type": ""} -->
-The `np.mean()` function is modular, and it can be easily combined with other functions to accomplish various tasks.
+The {func}`numpy.mean()` function is modular, and it can be easily combined with other functions to accomplish various tasks.
 
 When you write modular functions, you can reuse them for other workflows and projects. Some people even write their own **Python** packages for personal and professional use that contain custom functions for tasks that they have to complete regularly.
 

code-workflow-logic/python-conditionals.md

@@ -91,7 +91,7 @@ else:
 # Set x to 0
 x = 0
 
-# Compare x to 10; notice comparison is two equal signs and assignment is one eaual sign.
+# Compare x to 10; notice comparison is two equal signs and assignment is one equal sign.
 if x == 10:
     print("x is equal to 10.")    
 else:

code-workflow-logic/python-functions-multi-parameters.md

@@ -50,7 +50,7 @@ def function_name(data_1, data_2):
 ```
 
 <!-- #region -->
-When the function is called, a user can provide any value for `data_1` or `data_2` as input for that parameter (e.g., single-value variable, list, **numpy** array, **pandas** data frame column). 
+When the function is called, a user can provide any value for `data_1` or `data_2` as input for that parameter (e.g., single-value variable, list, {class}`numpy.ndarray`, {class}`pandas.DataFrame` column). 
 
 
 ## Write a Function with Multiple Parameters in Python
@@ -66,6 +66,7 @@ def multiply_values():
 
 Next, provide two placeholder variable names for the input parameters, as shown below. 
 
+
 ```python
 def multiply_values(x, y):
 ```
@@ -163,7 +164,6 @@ Use placeholder variable names that highlight the purpose of each parameter:
 def mean_mm_to_in(data_mm, axis_value):
 ```
 
-
 Next, add the code to first calculate the mean of the input array along a specified axis, and then to convert the mean values from millimeters to inches. 
 
 First, add the code line to calculate a mean along a specified axis. 
@@ -387,8 +387,8 @@ monthly_mean_in
 You can also write multi-parameter functions to combine other tasks into one function, such as downloading and reading data files into a **pandas** dataframe.
 
 Think about the code that you need to include in the function:
-1. download data file from URL: `et.data.get_data(url=file_url)`
-2. read data file into **pandas** dataframe: `pd.read_csv(path)`
+1. download data file from URL: {func}`et.data.get_data(url=file_url) <earthpy.data.get_data>`
+2. read data file into **pandas** dataframe: {func}`pd.read_csv(path) <pandas.read_csv>`
 
 From this code, you can see that you will need two input parameters for the combined function:
 1. the URL to the data file

code-workflow-logic/write-python-functions.md

@@ -88,22 +88,19 @@ In **Python**, the required parameters are provided within parenthesis `()`, as
 
 ```python
 def function_name(parameter):       
-```    
+```
 
 You can define an input parameter for a function using a placeholder variable, such as `data`, which represents the value or object that will be acted upon in the function. 
 
-
 ```python
 def function_name(data):
-```   
+```
 
 You can define a function using multiple parameters. 
 
-
 ```python
 def add_numbers(num_1, num_2):
-```  
-
+```
 
 ### Return Statement
 
@@ -214,7 +211,7 @@ Can the function `mm_to_in()` to take a list as an input? Look again at the code
 <!-- #region editable=true slideshow={"slide_type": ""} -->
 ## Call `help` on a custom function
 
-Just like you can call `help()` on a function provided by a **Python** package such as **pandas** (e.g. `help(pd.DataFrame)`, you can also call `help()` on custom functions.  
+Just like you can call `help()` on a function provided by a **Python** package such as **{mod}`pandas`** (e.g. {class}`help(pd.DataFrame) <pandas.DataFrame>`), you can also call `help()` on your own custom functions.  
 <!-- #endregion -->
 
 ```python editable=true slideshow={"slide_type": ""}
@@ -231,7 +228,7 @@ help(add_numbers)
 <!-- #region editable=true slideshow={"slide_type": ""} -->
 Notice that when you call `help()` on custom functions, you will see the docstring that was provided in the function definition.  
 
-The `help()` results for `np.mean` are simply longer because the docstring contains more information, such as sections for Notes and Examples. 
+The `help()` results for {func}`np.mean <numpy.mean>` are simply longer because the docstring contains more information, such as sections for Notes and Examples. 
 
 Combining related function calls into a single line of code allows you to write code that is much more efficient and less repetitive, assisting you in writing DRY code in **Python**. 
 

conf.py

@@ -58,6 +58,7 @@
     "sphinxext.opengraph",
     "sphinx_favicon",
     "sphinx.ext.todo",
+    "sphinx_codeautolink",
 ]
 
 # colon fence for card support in md
@@ -174,3 +175,31 @@
 
 # myst nb extension used to execute notebooks
 nb_execution_mode = "auto"
+
+# ------------------
+# Intersphinx & code linking
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ('https://pandas.pydata.org/docs/', None),
+    "earthpy": ("https://earthpy.readthedocs.io/en/latest/", None),
+    "matplotlib": ('https://matplotlib.org/stable/', None),
+}
+
+codeautolink_global_preface = """
+import numpy as np
+import pandas as pd
+import os
+"""
+codeautolink_concat_default=True
+
+# suppress all codeautolink warnings, we don't really care if it's busted
+suppress_warnings = [
+    "codeautolink.clean_block",
+    "codeautolink.parse_block",
+    "codeautolink.import_star",
+    "codeautolink.match_block",
+    "codeautolink.match_name",
+    "codeautolink.failed_resolve",
+]