From a3d72edd74846eb835a975e6affb9a26916f883d Mon Sep 17 00:00:00 2001 From: "Michael S. P. Kelley" Date: Tue, 23 Dec 2025 14:54:31 -0500 Subject: [PATCH 1/2] LinearPhaseFunc parameters need default values. --- sbpy/photometry/core.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sbpy/photometry/core.py b/sbpy/photometry/core.py index 8ed46b33..e388ba26 100644 --- a/sbpy/photometry/core.py +++ b/sbpy/photometry/core.py @@ -728,8 +728,8 @@ class LinearPhaseFunc(DiskIntegratedPhaseFunc): """ _unit = 'mag' - H = Parameter(description='Absolute magnitude') - S = Parameter(description='Linear slope (mag/deg)') + H = Parameter(description='Absolute magnitude', default=5 * u.mag) + S = Parameter(description='Linear slope (mag/deg)', default=0.04 * u.mag / u.deg) input_units = {'x': u.deg} @staticmethod From cc363b752a1d18bfe109a91d27d8888d3bfeac7c Mon Sep 17 00:00:00 2001 From: "Michael S. P. Kelley" Date: Tue, 23 Dec 2025 12:34:20 -0500 Subject: [PATCH 2/2] Use a substitutions file for docs so that astropy docstrings can be used --- docs/conf.py | 96 ++++++++++++++++++++++-------------------- docs/substitutions.txt | 34 +++++++++++++++ 2 files changed, 84 insertions(+), 46 deletions(-) create mode 100644 docs/substitutions.txt diff --git a/docs/conf.py b/docs/conf.py index a71dc65e..85b64215 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,26 +30,30 @@ import sys import matplotlib -matplotlib.use('agg') + +matplotlib.use("agg") try: from sphinx_astropy.conf.v1 import * except ImportError: - print('ERROR: the documentation requires the sphinx-astropy package to be' - ' installed') + print( + "ERROR: the documentation requires the sphinx-astropy package to be" + " installed" + ) sys.exit(1) # Get configuration information from setup.cfg from configparser import ConfigParser # noqa: E402 + conf = ConfigParser() -conf.read([os.path.join(os.path.dirname(__file__), '..', 'setup.cfg')]) -setup_cfg = dict(conf.items('metadata')) +conf.read([os.path.join(os.path.dirname(__file__), "..", "setup.cfg")]) +setup_cfg = dict(conf.items("metadata")) # -- General configuration ---------------------------------------------------- # By default, highlight as Python 3. -highlight_language = 'python3' +highlight_language = "python3" # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.2' @@ -60,16 +64,18 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns.append('_templates') +exclude_patterns.append("_templates") # This is added to the end of RST files - a good place to put substitutions to # be used globally. -rst_epilog += """ -""" +with open("substitutions.txt") as inf: + rst_epilog += inf.read() -extensions += ['sphinx.ext.intersphinx', - 'sphinx_automodapi.smart_resolver', - 'sphinx.ext.autosectionlabel'] +extensions += [ + "sphinx.ext.intersphinx", + "sphinx_automodapi.smart_resolver", + "sphinx.ext.autosectionlabel", +] # For example, index:Introduction for a section called Introduction that # appears in document index.rst. @@ -83,20 +89,19 @@ # -- Project information ------------------------------------------------------ # This does not *have* to match the package name, but typically does -project = setup_cfg['package_name'] -author = setup_cfg['author'] -copyright = '{0}, {1}'.format( - datetime.datetime.now().year, setup_cfg['author']) +project = setup_cfg["package_name"] +author = setup_cfg["author"] +copyright = "{0}, {1}".format(datetime.datetime.now().year, setup_cfg["author"]) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -__import__(setup_cfg['package_name']) -package = sys.modules[setup_cfg['package_name']] +__import__(setup_cfg["package_name"]) +package = sys.modules[setup_cfg["package_name"]] # The short X.Y version. -version = package.__version__.split('-', 1)[0] +version = package.__version__.split("-", 1)[0] # The full version, including alpha/beta/rc tags. release = package.__version__ @@ -113,68 +118,68 @@ # Add any paths that contain custom themes here, relative to this directory. # To use a different custom theme, add the directory containing the theme. -#html_theme_path = [] +# html_theme_path = [] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. To override the custom theme, set this to the # name of a builtin theme or the name of a custom theme in html_theme_path. -#html_theme = 'sphinx_rtd_theme' +# html_theme = 'sphinx_rtd_theme' # Please update these texts to match the name of your package. html_theme_options = { - 'logotext1': 'sb', # white, semi-bold - 'logotext2': 'py', # orange, light - 'logotext3': ':docs' # white, light + "logotext1": "sb", # white, semi-bold + "logotext2": "py", # orange, light + "logotext3": ":docs", # white, light } # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = '' +# html_logo = '' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = '' +# html_favicon = '' # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '' +# html_last_updated_fmt = '' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = '{0} v{1}'.format(project, release) +html_title = "{0} v{1}".format(project, release) # Output file base name for HTML help builder. -htmlhelp_basename = project + 'doc' +htmlhelp_basename = project + "doc" # -- Options for LaTeX output ------------------------------------------------- # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [('index', project + '.tex', project + u' Documentation', - author, 'manual')] +latex_documents = [ + ("index", project + ".tex", project + " Documentation", author, "manual") +] # -- Options for manual page output ------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [('index', project.lower(), project + u' Documentation', - [author], 1)] +man_pages = [("index", project.lower(), project + " Documentation", [author], 1)] # -- Options for the edit_on_github extension --------------------------------- -if eval(setup_cfg.get('edit_on_github')): - extensions += ['sphinx_astropy.ext.edit_on_github'] +if eval(setup_cfg.get("edit_on_github")): + extensions += ["sphinx_astropy.ext.edit_on_github"] - versionmod = __import__(setup_cfg['package_name'] + '.version') - edit_on_github_project = setup_cfg['github_project'] + versionmod = __import__(setup_cfg["package_name"] + ".version") + edit_on_github_project = setup_cfg["github_project"] if versionmod.version.release: edit_on_github_branch = "v" + versionmod.version.version else: @@ -184,18 +189,17 @@ edit_on_github_doc_root = "docs" # -- Resolving issue number to links in changelog ----------------------------- -github_issues_url = 'https://github.com/{0}/issues/'.format( - setup_cfg['github_project']) +github_issues_url = "https://github.com/{0}/issues/".format(setup_cfg["github_project"]) # -- compile list of field names # import compile_fieldnames # --- intersphinx setup -intersphinx_mapping['astroquery'] = ( - 'https://astroquery.readthedocs.io/en/stable/', None) +intersphinx_mapping["astroquery"] = ( + "https://astroquery.readthedocs.io/en/stable/", + None, +) -intersphinx_mapping['synphot'] = ( - 'https://synphot.readthedocs.io/en/stable/', None) +intersphinx_mapping["synphot"] = ("https://synphot.readthedocs.io/en/stable/", None) -intersphinx_mapping['astropy'] = ( - 'https://docs.astropy.org/en/stable/', None) +intersphinx_mapping["astropy"] = ("https://docs.astropy.org/en/stable/", None) diff --git a/docs/substitutions.txt b/docs/substitutions.txt new file mode 100644 index 00000000..0becf7d8 --- /dev/null +++ b/docs/substitutions.txt @@ -0,0 +1,34 @@ +.. ReST substitutions and links for the docs and docstrings. + +.. This file is included in the conf.py rst_epilog variable. + +.. Keep common items aligned with the astropy substitutions +.. (astropy/docs/common_links.rst) to avoid issues with inheriting +.. substitutions from astropy classes + +.. NumPy +.. |ndarray| replace:: :class:`numpy.ndarray` + +.. Astropy +.. Coordinates +.. |Angle| replace:: `~astropy.coordinates.Angle` +.. |Latitude| replace:: `~astropy.coordinates.Latitude` +.. |Longitude| replace:: :class:`~astropy.coordinates.Longitude` +.. |BaseFrame| replace:: `~astropy.coordinates.BaseCoordinateFrame` +.. |SkyCoord| replace:: :class:`~astropy.coordinates.SkyCoord` + +.. Table +.. |Column| replace:: :class:`~astropy.table.Column` +.. |MaskedColumn| replace:: :class:`~astropy.table.MaskedColumn` +.. |TableColumns| replace:: :class:`~astropy.table.TableColumns` +.. |Row| replace:: :class:`~astropy.table.Row` +.. |Table| replace:: :class:`~astropy.table.Table` +.. |QTable| replace:: :class:`~astropy.table.QTable` + +.. Time +.. |Time| replace:: :class:`~astropy.time.Time` + +.. Units +.. |PhysicalType| replace:: :class:`~astropy.units.PhysicalType` +.. |Quantity| replace:: :class:`~astropy.units.Quantity` +.. |Unit| replace:: :class:`~astropy.units.UnitBase`