From e40095139ba3e1581e41606f1956127bfe57c834 Mon Sep 17 00:00:00 2001 From: Teal Date: Mon, 23 Oct 2023 15:50:31 -0700 Subject: [PATCH] Generate reference using sphinx-autoapi sphinx-autoapi automatically generates a complete reference by *statically* parsing the source files in our code. This is a new, straightforward way to interact with existing and new documentation otherwise only accessible through docstrings. This does not propogate to any other pages in the documentation not generated at the top-level (e.g., the astrodata/recipe manuals). But these are still included in the reference API regardless. This also allows smart linking to the API reference from within docstrings. e.g., if one wants to reference the AstroData class, you can just do the following: :py:class:`~astrodata.core.AstroData` This creates a link to the reference entry for AstroData's class. If desired it could be included using a replacement directive .. |AstroData| replace:: :py:class:`~astrodata.core.AstroData` There are other options/configurations to streamline this a bit. This commit also build fine, but there are some circular references and duplicate object references that need to be either resolved or better handled. Obviously, there is no good way to implement this other than finding references in the docstrings and changing them "manually" if they don't properly link to the right place. I'm writing a script for the astrodata package to maintain a list of these kinds of broken links that could probably be applied to this. But, no ETC on that. --- doc/DRAGONS/conf.py | 75 +++++++++++++++++++++++++++++---------------- 1 file changed, 49 insertions(+), 26 deletions(-) diff --git a/doc/DRAGONS/conf.py b/doc/DRAGONS/conf.py index c3fc8dc52..6e21384f9 100644 --- a/doc/DRAGONS/conf.py +++ b/doc/DRAGONS/conf.py @@ -33,9 +33,15 @@ 'sphinx.ext.imgmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', + 'sphinx.ext.autosummary', + # 'sphinx.ext.inheritance_diagram', + 'autoapi.extension' # 'sphinx.ext.githubpages', ] +# Turn on autosummary +autosummary_generate = True + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -79,7 +85,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '*test*/', '*/generated/'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -112,11 +118,12 @@ #html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme' - # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + 'logo_url' : 'https://dragons.readthedocs.io/', +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -187,7 +194,6 @@ # Output file base name for HTML help builder. htmlhelp_basename = 'DRAGONS' - # -- Options for LaTeX output -------------------------------------------------- latex_elements = { @@ -209,8 +215,8 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'DRAGONS.tex', 'DRAGONS', - 'Gemini Observatory', 'manual'), + ('index', 'DRAGONS.tex', 'DRAGONS', + 'Gemini Observatory', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -232,8 +238,6 @@ # If false, no module index is generated. #latex_domain_indices = True - - # -- Options for manual page output -------------------------------------------- # One entry per manual page. List of tuples @@ -245,17 +249,15 @@ # If true, show URL addresses after external links. #man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ + # -- Options for Texinfo output ------------------------------------------------ # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'DRAGONS', 'DRAGONS', - 'Gemini Observatory', 'DRAGONS', 'One line description of project.', - 'Miscellaneous'), + ('index', 'DRAGONS', 'DRAGONS', + 'Gemini Observatory', 'DRAGONS', 'One line description of project.', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. @@ -266,29 +268,24 @@ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' - - -# Example configuration for intersphinx: refer to the Python standard library. + # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} # Activate the todos todo_include_todos = True # Adding style in order to have the todos show up in a red box. - - def setup(app): - app.add_css_file('todo-styles.css') - app.add_css_file('rtd_theme_overrides.css') - app.add_css_file('css/rtd_theme_overrides_references.css') - app.add_css_file('fonts.css') - + app.add_css_file('todo-styles.css') + app.add_css_file('rtd_theme_overrides.css') + app.add_css_file('css/rtd_theme_overrides_references.css') + app.add_css_file('fonts.css') rst_epilog = """ .. role:: raw-html(raw) - :format: html + :format: html -.. |GMOSImgTut| replace:: :raw-html:`GMOS Imaging Data Reduction Tutorial` +.. |GMOSImgTut| replace:: :raw-html:`GMOS Imaging Data Reduction Tutorial` .. |NIRIImgTut| replace:: :raw-html:`NIRI Imaging Data Reduction Tutorial` .. |F2ImgTut| replace:: :raw-html:`Flamingos-2 Imaging Data Reduction Tutorial` .. |GSAOIImgTut| replace:: :raw-html:`GSAOI Imaging Data Reduction Tutorial` @@ -309,3 +306,29 @@ def setup(app): .. |RSUserShow| replace:: http://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/ """.format(v = rtdurl) + +# autoapi +autoapi_dirs = [ + '../../astrodata/', + '../../gemini_instruments/', + '../../geminidr/', + '../../gempy/', + '../../recipe_system/' +] + +autoapi_ignore = [ + '*test*', + '*/doc/*', + '*conf.py', + '*sscripts/*' +] + +autoapi_options = [ + 'members', + 'undoc-members', + 'show-inheritance', + # 'show-module-summary', + # 'show-inheritance-diagram', +] + +autoapi_member_order = 'groupwise' \ No newline at end of file