From c95edf57393fdaa9d6adff3c09636eed3973e8d2 Mon Sep 17 00:00:00 2001 From: "Brandon N. Benton" Date: Fri, 23 Aug 2024 17:57:00 -0600 Subject: [PATCH] doc fixes --- .github/workflows/gh_pages.yml | 2 +- .gitignore | 3 ++ docs/source/conf.py | 76 +++++++++++++++++++--------------- 3 files changed, 46 insertions(+), 35 deletions(-) diff --git a/.github/workflows/gh_pages.yml b/.github/workflows/gh_pages.yml index de053b3..72345d4 100644 --- a/.github/workflows/gh_pages.yml +++ b/.github/workflows/gh_pages.yml @@ -18,7 +18,7 @@ jobs: python -m pip install --upgrade pip python -m pip install . python -m pip install sphinx - python -m pip install sphinx_rtd_theme + python -m pip install sphinx_book_theme python -m pip install sphinx-click - name: build documentation run: | diff --git a/.gitignore b/.gitignore index 1a46f62..5cc1024 100644 --- a/.gitignore +++ b/.gitignore @@ -125,3 +125,6 @@ scratch # VSCode config .vscode + + +*_autosummary diff --git a/docs/source/conf.py b/docs/source/conf.py index 2ae53ba..c905551 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,14 +16,13 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os -import sphinx_rtd_theme import sys # -- Project information ----------------------------------------------------- -project = 'farms' -copyright = '2020, Alliance for Sustainable Energy, LLC' -author = 'Grant Buster' +project = "farms" +copyright = "2020, Alliance for Sustainable Energy, LLC" +author = "Grant Buster" pkg = os.path.dirname(os.path.abspath(os.path.dirname(__file__))) pkg = os.path.dirname(pkg) @@ -32,7 +31,7 @@ with open(os.path.join(pkg, "farms", "version.py"), encoding="utf-8") as f: v = f.read() -v = v.split('=')[-1].strip().strip('"').strip("'") +v = v.split("=")[-1].strip().strip('"').strip("'") # The short X.Y version version = v # The full version, including alpha/beta/rc tags @@ -48,33 +47,37 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", "sphinx.ext.doctest", - "sphinx.ext.intersphinx", "sphinx.ext.coverage", - "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.githubpages", + "sphinx_click.ext", + "sphinx_tabs.tabs", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.extlinks", + "sphinx.ext.mathjax", "sphinx.ext.napoleon", - "sphinx_rtd_theme", + "sphinx_autosummary_accessors", + "sphinx_copybutton", ] autosummary_generate = True -intersphinx_mapping = {'python': ('http://docs.python.org/3.8', None)} +intersphinx_mapping = {"python": ("http://docs.python.org/3.8", None)} # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -source_suffix = '.rst' +source_suffix = ".rst" # source_parsers = {'.md': MarkdownParser} # The master toctree document. -master_doc = 'index' +master_doc = "index" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -89,7 +92,7 @@ exclude_patterns = ["_build", ".DS_Store"] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # -- Options for HTML output ------------------------------------------------- @@ -97,8 +100,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_theme = "sphinx_book_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 @@ -106,6 +108,9 @@ # html_theme_options = {"navigation_depth": 4, "collapse_navigation": False} +# user starts in light mode +default_dark_mode = False + html_context = { "display_github": True, "github_user": "nrel", @@ -118,7 +123,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -134,7 +139,7 @@ # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'farmsdoc' +htmlhelp_basename = "farmsdoc" # -- Options for LaTeX output ------------------------------------------------ @@ -143,15 +148,12 @@ # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. # # 'preamble': '', - # Latex figure (float) alignment # # 'figure_align': 'htbp', @@ -161,8 +163,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'farms.tex', 'farms Documentation', - 'Grant Buster', 'manual'), + (master_doc, "farms.tex", "farms Documentation", "Grant Buster", "manual"), ] @@ -170,10 +171,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'farms', 'farms Documentation', - [author], 1) -] +man_pages = [(master_doc, "farms", "farms Documentation", [author], 1)] # -- Options for Texinfo output ---------------------------------------------- @@ -182,17 +180,27 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'farms', 'farms Documentation', - author, 'farms', - 'The Fast All-sky Radiation Model for Solar applications (FARMS)', - 'Miscellaneous'), + ( + master_doc, + "farms", + "farms Documentation", + author, + "farms", + "The Fast All-sky Radiation Model for Solar applications (FARMS)", + "Miscellaneous", + ), ] # -- Extension configuration ------------------------------------------------- -autoclass_content = 'both' -autodoc_member_order = 'bysource' +autosummary_generate = True # Turn on sphinx.ext.autosummary +autoclass_content = "both" # Add __init__ doc (ie. params) to class summaries +autodoc_member_order = "bysource" +autodoc_inherit_docstrings = True # If no docstring, inherit from base class +add_module_names = False # Remove namespaces from class/method signatures +# Remove 'view source code' from top of page (for html, not python) +html_show_sourcelink = False numpy_show_class_member = True napoleon_google_docstring = False napoleon_use_param = False