diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index b76c786..ee5faff 100644 --- a/.github/workflows/documentation.yaml +++ b/.github/workflows/documentation.yaml @@ -10,7 +10,7 @@ jobs: - uses: actions/setup-python@v3 - name: Install dependencies run: | - pip install sphinx sphinx_rtd_theme sphinx_book_theme + pip install sphinx sphinx_rtd_theme sphinx_book_theme sphinx_autosummary_accessors sphinx_copybutton nbsphinx - name: Sphinx build run: | sphinx-build docs _build diff --git a/docs/conf.py b/docs/conf.py index e45ab33..cf837dd 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,11 +10,13 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +from typing import Dict -#import sphinx_autosummary_accessors +sys.path.insert(0, os.path.abspath('.')) + +import sphinx_autosummary_accessors # -- Project information ----------------------------------------------------- @@ -31,10 +33,49 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme'] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_autosummary_accessors", + "sphinx_copybutton", + "nbsphinx", +] + +# autosummary and autodoc configurations +autosummary_generate = True + +autodoc_member_order = "bysource" +autodoc_default_options = { + "members": True, + "undoc-members": True, + "private-members": True, +} +autodoc_typehints = "none" + +# Napoleon configurations +napoleon_google_docstring = False +napoleon_numpy_docstring = True +napoleon_use_param = False +napoleon_use_rtype = False +napoleon_preprocess_types = True + +# sphinx-copybutton configurations +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates", sphinx_autosummary_accessors.templates_path] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" + +# The master toctree document. +master_doc = "index" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -45,8 +86,13 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "demos/1-25-23-cwss-seminar/xsearch-xcdat-example.ipynb", +] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -91,3 +137,69 @@ # 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'] + + +# -- Options for HTMLHelp output --------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "xcdatdoc" + + +# -- Options for LaTeX output ------------------------------------------ + +latex_elements: Dict[str, str] = { + # 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', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto, manual, or own class]). +latex_documents = [ + (master_doc, "xcdat.tex", "xCDAT Documentation", "Tom Vo", "manual"), +] + + +# -- Options for manual page output ------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "xcdat", "xCDAT Documentation", [author], 1)] + + +# -- 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 = [ + ( + master_doc, + "xcdat", + "xCDAT Documentation", + author, + "xcdat", + "One line description of project.", + "Miscellaneous", + ), +] + + +def html_page_context(app, pagename, templatename, context, doctree): + # Disable edit button for docstring generated pages + if "generated" in pagename: + context["theme_use_edit_page_button"] = False + + +def setup(app): + app.connect("html-page-context", html_page_context) \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index d4d9896..9e2d2bb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,7 @@ +PCMDI UTILS +=========== + Welcome to PCMDI UTILS documentation! -=============================================== .. toctree:: :maxdepth: 2