From 3f7ab3f77c9ad7ab479636419031279d15c6f0a7 Mon Sep 17 00:00:00 2001 From: Brian Blaylock Date: Mon, 18 Dec 2023 21:47:28 -0800 Subject: [PATCH 1/3] update sphinx config and add version switcher --- docs/_static/switcher.json | 22 +++++++++ docs/conf.py | 98 ++++++++++++++++++++++++-------------- 2 files changed, 83 insertions(+), 37 deletions(-) create mode 100644 docs/_static/switcher.json diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json new file mode 100644 index 0000000..e0a8e64 --- /dev/null +++ b/docs/_static/switcher.json @@ -0,0 +1,22 @@ +[ + { + "version": "latest", + "url": "https://goes2go.readthedocs.io/en/latest/", + "is_latest": true + }, + { + "name": "stable", + "version": "stable", + "url": "https://goes2go.readthedocs.io/en/stable/" + }, + { + "name": "2023.12.0", + "version": "2023.12.0", + "url": "https://goes2go.readthedocs.io/en/2023.12.0/" + }, + { + "name": "2023.8.0", + "version": "2023.8.0", + "url": "https://goes2go.readthedocs.io/en/2023.8.0/" + } +] diff --git a/docs/conf.py b/docs/conf.py index 19df0f6..400e28f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,21 +12,28 @@ # import os import sys -import goes2go.data ## Required for accessors to be documented +from datetime import datetime + +import pydata_sphinx_theme + +import goes2go +import goes2go.data # # Required for accessors to be documented sys.path.insert(0, os.path.abspath("../..")) -import pydata_sphinx_theme -from datetime import datetime +# The full version, including alpha/beta/rc/post tags +release = goes2go.__version__ + +# The version, excluding alpha/beat/rc/tags +version = ".".join([str(i) for i in goes2go.__version_tuple__]) + # -- Project information ----------------------------------------------------- utc_now = datetime.utcnow().strftime("%H:%M UTC %d %b %Y") -project = "GOES-2-g- Docs" +project = "goes2go" copyright = f"{datetime.utcnow():%Y}, Brian K. Blaylock. ♻ Updated: {utc_now}" -author = "Brian K. Blaylock" - -release = "0.1" +author = f"Brian K. Blaylock" # -- General configuration --------------------------------------------------- @@ -37,20 +44,22 @@ "nbsphinx", "sphinx.ext.autodoc", "sphinx.ext.autosummary", - "sphinx.ext.viewcode", "sphinx.ext.autosectionlabel", "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_copybutton", + "sphinx.ext.todo", "sphinx_design", "autodocsumm", "sphinx_markdown_tables", "myst_parser", + "sphinxcontrib.mermaid", ] autosummary_generate = True # Turn on sphinx.ext.autosummary # MyST Docs: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html myst_enable_extensions = [ - "colon_fence", "linkify", # Autodetects URL links in Markdown files ] @@ -67,7 +76,6 @@ source_suffix = { ".rst": "restructuredtext", - ".txt": "markdown", ".md": "markdown", } @@ -77,47 +85,75 @@ # 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 = ["_build", "Thumbs.db", ".DS_Store", ".ipynb_checkpoints", ".vscode"] - +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + ".ipynb_checkpoints", + ".vscode", +] -# --- Options for HTML output ------------------------------------------------- +# ---- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = "pydata_sphinx_theme" +html_favicon = "_static/wxicon.png" html_theme_options = { - "github_url": "https://github.com/blaylockbk/goes2go", - "twitter_url": "https://twitter.com/blaylockbk", - "navbar_end": ["theme-switcher", "navbar-icon-links.html", "search-field.html"], - "google_analytics_id": "G-NWK8MJNNGX", - "use_edit_page_button": True, - "show_toc_level": 1, "external_links": [ + { + "name": "SynopticPy", + "url": "https://synopticpy.readthedocs.io/", + }, { "name": "Herbie", "url": "https://herbie.readthedocs.io/", }, + ], + "header_links_before_dropdown": 4, + "icon_links": [ { - "name": "SynopticPy", - "url": "https://synopticpy.readthedocs.io/", + "name": "Twitter", + "url": "https://twitter.com/blaylockbk", + "icon": "fa-brands fa-twitter", + }, + { + "name": "GitHub", + "url": "https://github.com/blaylockbk/goes2go", + "icon": "fa-brands fa-github", + }, + { + "name": "PyPI", + "url": "https://pypi.org/project/goes2go", + "icon": "fa-custom fa-pypi", }, ], "logo": { "image_light": "goes2go_logo.png", "image_dark": "goes2go_logo.png", }, + "use_edit_page_button": True, + "show_toc_level": 1, + "navbar_align": "left", + "show_version_warning_banner": True, + "navbar_center": ["version-switcher", "navbar-nav"], + "footer_start": ["copyright"], + "footer_center": ["sphinx-version"], + "switcher": { + "json_url": "https://goes2go.readthedocs.io/en/latest/_static/switcher.json", + "version_match": os.environ.get("READTHEDOCS_VERSION"), + }, } html_sidebars = {} -html_favicon = "_static/wxicon.png" html_context = { "github_user": "blaylockbk", "github_repo": "goes2go", - "github_version": "main", # Make changes to the master branch + "github_version": "main", # Make changes to the main branch "doc_path": "docs", } @@ -125,8 +161,9 @@ # 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", "../images"] - html_css_files = ["brian_style.css"] +html_js_files = [] +todo_include_todos = True # Set autodoc defaults autodoc_default_options = { @@ -146,16 +183,3 @@ "imageio", "siphon", ] - - -""" -IMPORTANT NOTES ABOUT PUBLISHING TO GITHUB PAGES ------------------------------------------------ -1. Must have an empty file called .nojekell in this directory. - -2. Include an index.html file to redirect to the actual html build - Something like this in that file (yes, only one line)... - - -3. -""" From 2488145457f2607f75aab278eab1d502826200c2 Mon Sep 17 00:00:00 2001 From: Brian Blaylock Date: Mon, 18 Dec 2023 21:51:14 -0800 Subject: [PATCH 2/3] add docs dependency --- pyproject.toml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 3fc02e8..5d6865b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,6 @@ classifiers = [ "License :: OSI Approved :: MIT License", "Intended Audience :: Science/Research", "Topic :: Scientific/Engineering :: Atmospheric Science", - ] keywords = [ "weather", @@ -58,6 +57,7 @@ docs = [ "myst-parser", "nbconvert", "nbsphinx", + "sphinx-copybutton", "pydata-sphinx-theme", "recommonmark", "sphinx", @@ -66,7 +66,6 @@ docs = [ "sphinx-markdown-tables", "sphinxcontrib-mermaid", ] - test = ["pytest", "black", "isort"] [build-system] From fbdba849f9dd43dfb1fc1f60293299c8221df86f Mon Sep 17 00:00:00 2001 From: Brian Blaylock Date: Mon, 18 Dec 2023 21:56:15 -0800 Subject: [PATCH 3/3] import version --- goes2go/__init__.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/goes2go/__init__.py b/goes2go/__init__.py index 664a02c..46e6ede 100644 --- a/goes2go/__init__.py +++ b/goes2go/__init__.py @@ -5,6 +5,18 @@ import warnings from pathlib import Path +__author__ = "Brian K. Blaylock" + + +try: + ## TODO: Will the `_version.py` file *always* be present? + ## TODO: What if the person doesn't do "pip install" + from ._version import __version__, __version_tuple__ +except: + __version__ = "unknown" + __version_tuple__ = (999, 999, 999) + + import toml # =======================================================================