Docs updates

docs/conf.py

@@ -6,16 +6,22 @@
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 
+import datetime
+import inspect
+import sys
+from os.path import relpath, dirname
 
 # -- Project information -----------------------------------------------------
 
 project = 'gadfly'
-copyright = '2022, Brett M. Morris'
 author = 'Brett M. Morris'
+copyright = f"{datetime.datetime.now().year}, {author}"  # noqa: A001
 
 # The full version, including alpha/beta/rc tags
+import gadfly
 from gadfly import __version__
 release = __version__
+dev = "dev" in release
 
 # -- General configuration ---------------------------------------------------
 
@@ -32,6 +38,7 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.doctest',
     'sphinx.ext.mathjax',
+    'sphinx.ext.linkcode',
     'sphinx_automodapi.automodapi',
     'sphinx_automodapi.smart_resolver',
     'sphinx.ext.autosectionlabel',
@@ -54,23 +61,29 @@
 # The master toctree document.
 master_doc = 'index'
 
+# Treat everything in single ` as a Python reference.
+default_role = 'py:obj'
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'https://docs.python.org/': None,
+    'python': ('https://docs.python.org/', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
     'celerite2': ('https://celerite2.readthedocs.io/en/latest/', None),
     'astropy': ('https://docs.astropy.org/en/stable/', None),
     'lightkurve': ('https://docs.lightkurve.org/', None),
     'matplotlib': ('http://matplotlib.org/stable', None),
-    'tynt': ('https://tynt.readthedocs.io/en/latest/', None)
+    'tynt': ('https://tynt.readthedocs.io/en/latest/', None),
 }
 
 # -- Options for HTML output -------------------------------------------------
 
+github_issues_url = 'https://github.com/bmorris3/gadfly/issues/'
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
+html_copy_source = False
 html_theme = 'sphinx_book_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -80,9 +93,10 @@
 html_favicon = "assets/logo.ico"
 
 html_theme_options = {
-    "logo_only": True,
+    "use_edit_page_button": True,
     "use_download_button": True,
     "repository_url": "https://github.com/bmorris3/gadfly",
+    "github_url": "https://github.com/bmorris3/gadfly",
     "repository_branch": "main",
     "path_to_docs": "docs",
 }
@@ -91,12 +105,97 @@
 autodoc_inherit_docstrings = True
 
 html_context = {
-    "display_github": True,
     "github_user": "bmorris3",
     "github_repo": "gadfly",
     "github_version": "main",
     "conf_py_path": "docs/",
+    "default_mode": "light",
+    "to_be_indexed": ["stable", "latest"],
+    "is_development": dev,
+    "doc_path": "docs",
+    "display_github": True,
 }
 
 autosectionlabel_prefix_document = True
 autoclass_content = 'both'
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = '{0}'.format(project)
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = project + 'doc'
+
+# Prefixes that are ignored for sorting the Python module index
+modindex_common_prefix = ["gadfly."]
+
+suppress_warnings = ['autosectionlabel.*']
+
+
+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 Exception:
+            return None
+
+    # strip decorators, which would resolve to the source of the decorator
+    # possibly an upstream bug in getsourcefile, bpo-1764286
+    try:
+        unwrap = inspect.unwrap
+    except AttributeError:
+        pass
+    else:
+        obj = unwrap(obj)
+
+    fn = None
+    lineno = None
+
+    if fn is None:
+        try:
+            fn = inspect.getsourcefile(obj)
+        except Exception:
+            fn = None
+        if not fn:
+            return None
+
+        # Ignore re-exports as their source files are not within the numpy repo
+        module = inspect.getmodule(obj)
+        if module is not None and not module.__name__.startswith("shone"):
+            return None
+
+        try:
+            source, lineno = inspect.getsourcelines(obj)
+        except Exception:
+            lineno = None
+
+        fn = relpath(fn, start=dirname(gadfly.__file__))
+
+    if lineno:
+        linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
+    else:
+        linespec = ""
+
+    if 'dev' in gadfly.__version__:
+        return "https://github.com/bmorris3/shone/blob/main/shone/%s%s" % (
+           fn, linespec)
+    else:
+        return "https://github.com/bmorris3/shone/blob/v%s/shone/%s%s" % (
+           gadfly.__version__, fn, linespec)
+
+
+plot_formats = [('png', 250)]

docs/gadfly/start.rst

@@ -118,11 +118,11 @@ out their key properties:
     import astropy.units as u
 
     # Some (randomly chosen) real stars from Huber et al. (2011)
-    kics = [9333184, 8416311, 8624155, 3120486, 9650527]
-    masses = [0.9, 1.5, 1.8, 1.9, 2.0] * u.M_sun
-    radii = [10.0, 2.2, 8.8, 6.7, 10.9] * u.R_sun
-    temperatures = [4919, 6259, 4944, 4929, 4986] * u.K
-    luminosities = [52.3, 6.9, 41.2, 23.9, 65.4] * u.L_sun
+    kics = [9333184, 8624155, 3120486]
+    masses = [0.9, 1.8, 1.9] * u.M_sun
+    radii = [10.0, 8.8, 6.7] * u.R_sun
+    temperatures = [4919, 4944, 4929] * u.K
+    luminosities = [52.3, 41.2, 23.9] * u.L_sun
 
     stellar_props = [
         kics, masses, radii, temperatures, luminosities
@@ -142,6 +142,8 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`.
     import matplotlib.pyplot as plt
     fig, ax = plt.subplots(figsize=(8, 4))
 
+    plot_frequencies = np.geomspace(0.1, 300, 25_000) * u.uHz
+
     # iterate over each star:
     for i, (kic, mass, rad, temp, lum) in enumerate(zip(*stellar_props)):
         # scale the set of solar hyperparameters for each
@@ -161,12 +163,12 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`.
         # Plot the kernel's PSD:
         kernel.plot(
             ax=ax,
-            n_samples=5e3
+            freq=plot_frequencies
         )
 
     # Label the legend, set the power range in plot:
     legend = ax.legend(title='Simulated kernels')
-    ax.set_ylim(1e-1, 1e6)
+    ax.set_ylim(1, 1e6)
 
 .. plot::
 
@@ -178,14 +180,16 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`.
 
     # Some (randomly chosen) real stars from Huber et al. (2011)
     # https://ui.adsabs.harvard.edu/abs/2011ApJ...743..143H/abstract
-    kics = [9333184, 8416311, 8624155, 3120486, 9650527]
-    masses = [0.9, 1.5, 1.8, 1.9, 2.0] * u.M_sun
-    radii = [10.0, 2.2, 8.8, 6.7, 10.9] * u.R_sun
-    temperatures = [4919, 6259, 4944, 4929, 4986] * u.K
-    luminosities = [52.3, 6.9, 41.2, 23.9, 65.4] * u.L_sun
+    kics = [9333184, 8624155, 3120486]
+    masses = [0.9, 1.8, 1.9] * u.M_sun
+    radii = [10.0, 8.8, 6.7] * u.R_sun
+    temperatures = [4919, 4944, 4929] * u.K
+    luminosities = [52.3, 41.2, 23.9] * u.L_sun
 
     stellar_props = [kics, masses, radii, temperatures, luminosities]
 
+    plot_frequencies = np.geomspace(0.1, 300, 25_000) * u.uHz
+
     # iterate over each star:
     for i, (kic, mass, radius, temperature, luminosity) in enumerate(zip(*stellar_props)):
         # scale the set of solar hyperparameters for each
@@ -201,12 +205,12 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`.
         # Plot the kernel's PSD:
         kernel.plot(
             ax=ax,
-            n_samples=5e3
+            freq=plot_frequencies
         )
 
     # Label the legend, set the power range in plot:
     legend = ax.legend(title='Simulated kernels')
-    ax.set_ylim(1e-1, 1e6)
+    ax.set_ylim(1, 1e6)
 
 The resulting plot has "simulated" power spectra for the five stars, built by
 scaling the observed solar oscillations and granulation, which were parameterized by

docs/gadfly/validation.rst

@@ -108,25 +108,24 @@ Now we'll call a big loop to do most of the work:
         # Compute the power spectrum:
         ps = PowerSpectrum.from_light_curve(
             lc,
-            name=target_name,
-            detrend_poly_order=1
+            name=target_name
         )
 
         # Plot the binned PSD and the kernel PSD. This plot function
         # takes lots of keyword arguments so you can fine-tune your
         # plots:
-        obs_kw = dict(color='k', marker='.', lw=0)
+        obs_kw = dict(color='k', marker='.', lw=0, alpha=0.4, zorder=-10)
 
         ps.bin(1_500).plot(
             ax=axis,
             kernel=kernel,
             freq=ps.frequency,
             obs_kwargs=obs_kw,
             legend=True,
-            n_samples=5e3,
+            n_samples=1e4,
             label_kernel='Pred. kernel',
             label_obs=target_name,
-            kernel_kwargs=dict(color=f'C{i}', alpha=0.9),
+            kernel_kwargs=dict(color=f'C{i}', lw=1.5),
             title=""
         )
 
@@ -196,22 +195,21 @@ Ok, let's see the output:
         # Compute the power spectrum:
         ps = PowerSpectrum.from_light_curve(
             lc, name=target_name,
-            detrend_poly_order=1
         )
 
-        obs_kw = dict(color='k', marker='.', lw=0)
+        obs_kw = dict(color='k', marker='.', lw=0, alpha=0.4, zorder=-10)
 
         # Plot the binned PSD of the light curve:
-        ps.bin(1_500).plot(
+        ps.bin(1_000).plot(
             ax=axis,
             kernel=kernel,
             freq=ps.frequency,
             legend=True,
-            n_samples=5e3,
+            n_samples=1e4,
             label_kernel='Pred. kernel',
             label_obs=target_name,
             obs_kwargs=obs_kw,
-            kernel_kwargs=dict(color=f'C{i}', alpha=0.9),
+            kernel_kwargs=dict(color=f'C{i}', lw=1.5),
             title=""
         )
 
@@ -252,17 +250,17 @@ kernel:
 
 .. code-block:: python
 
-        light_curve = search_lightcurve(
-            name, mission='Kepler', quarter=range(6), cadence='short'
-        ).download_all()
+    light_curve = search_lightcurve(
+        name, mission='Kepler', quarter=range(6), cadence='short'
+    ).download_all()
 
-        kernel = (
-            # kernel for scaled stellar oscillations and granulation
-            StellarOscillatorKernel(hp, texp=1 * u.min) +
+    kernel = (
+        # kernel for scaled stellar oscillations and granulation
+        StellarOscillatorKernel(hp, texp=1 * u.min) +
 
-            # add in a kernel for Kepler shot noise
-            ShotNoiseKernel.from_kepler_light_curve(light_curve)
-        )
+        # add in a kernel for Kepler shot noise
+        ShotNoiseKernel.from_kepler_light_curve(light_curve)
+    )
 
 Let's now run the adapted code on the first two stars (click the "Source code" link below
 to see the code that generates this plot):
@@ -320,19 +318,18 @@ to see the code that generates this plot):
         ps = PowerSpectrum.from_light_curve(
             light_curve, name=name,
             detrend_poly_order=1
-        ).bin(1_500)
+        ).bin(500)
 
-        kernel_kw = dict(color=f"C{i}", alpha=0.9)
-        obs_kw = dict(color='k', marker='.', lw=0)
-        freq = np.logspace(-0.5, 4, int(1e3)) * u.uHz
+        kernel_kw = dict(color=f"C{i}", lw=1.5)
+        obs_kw = dict(color='k', marker='.', lw=0, alpha=0.5, zorder=-10)
+        freq = np.logspace(-0.5, 4, int(1e4)) * u.uHz
         kernel.plot(
             ax=axis,
             p_mode_inset=False,
             freq=freq,
             obs=ps,
             obs_kwargs=obs_kw,
             kernel_kwargs=kernel_kw,
-            n_samples=1e4,
             title=""
         )
 
@@ -407,7 +404,7 @@ Kepler would observe for each target.
         ps = PowerSpectrum.from_light_curve(
             light_curve, name=name,
             detrend_poly_order=3,
-        ).bin(500)
+        ).bin(100)
 
         # adjust some plot settings:
         kernel_kw = dict(color=f"C{i}", alpha=0.9)

docs/index.rst

@@ -10,11 +10,6 @@ This is the documentation for ``gadfly``, a Python package for generating photom
 stars with granulation and p-mode oscillations. The source code is available
 `on GitHub <https://github.com/bmorris3/gadfly>`_.
 
-.. note::
-
-    ``gadfly`` is under active development. If you run into any issues, please `let us
-    know on GitHub <https://github.com/bmorris3/gadfly/issues>`_.
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents: