docs/global-nav

CHANGES.rst

@@ -3,6 +3,7 @@
 
 - Changes documentation configuration settings to make this consistent with other asdf-related projects [#61]
 - Fix typo in latex logo path [#62]
+- Adds global navigation in docs top bar [#63]
 
 0.3.0 (2024-03-09)
 ------------------

docs/_static/custom.css

@@ -41,3 +41,13 @@ div.highlight-python {
 div.highlight-python:active {
     width: 150%
 }
+
+/* Top Banner Navigation
+-------------------------------------------------- */
+.announcement-content a {
+    padding-right: 1em;
+  }
+
+.announcement-content a:hover {
+  color: fuchsia;
+}

docs/conf.py

@@ -31,6 +31,7 @@
 copyright = f"{datetime.datetime.now().year}, {author}"
 
 release = get_distribution(configuration["name"]).version
+# The short X.Y version
 version = ".".join(release.split(".")[:2])
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -44,14 +45,24 @@
     # main project
     "asdf-website": ("https://www.asdf-format.org/en/latest", None),
     # other subprojects
-    "asdf": ("https://asdf.readthedocs.io/en/latest/", None),
+    "asdf": ("https://www.asdf-format.org/projects/asdf/en/stable/", None),
     "asdf-standard": ("https://asdf-standard.readthedocs.io/en/latest/", None),
     "asdf-transform-schemas": ("https://www.asdf-format.org/projects/asdf-transform-schemas/en/latest/", None),
     "asdf-wcs-schemas": ("https://www.asdf-format.org/projects/asdf-wcs-schemas/en/latest/", None),
 }
 
 intersphinx_mapping.update(subprojects)  # noqa
 
+# Adds a global navigation in the topbar - consistent across subprojects
+globalnavlinks = {
+    "ASDF Projects": "https://www.asdf-format.org",
+    "Tutorials": "https://www.asdf-format.org/en/latest/tutorials/index.html",
+    "Community": "https://www.asdf-format.org/en/latest/community/index.html",
+}
+topbanner = ""
+for text, link in globalnavlinks.items():
+    topbanner += f"<a href={link}>{text}</a>"
+
 # To perform a Sphinx version check that needs to be more specific than
 # major.minor, call `check_sphinx_version("x.y.z")` here.
 # check_sphinx_version("1.2.1")
@@ -82,7 +93,6 @@
 # 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 = "furo"
-html_theme_options = {}
 
 html_static_path = ["_static"]
 
@@ -98,6 +108,7 @@
 html_theme_options = {
     "light_logo": "images/logo-light-mode.png",
     "dark_logo": "images/logo-dark-mode.png",
+    "announcement": topbanner,
 }
 
 pygments_style = "monokai"
@@ -111,7 +122,7 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = f"{project} v{release}"
+html_title = f"{project.replace('_', ' ')} v{release}"
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = project + "doc"
@@ -148,13 +159,13 @@
 extensions += ["sphinx_asdf", "sphinx.ext.intersphinx", "sphinx.ext.extlinks"]  # noqa
 
 
-def setup(app):
-    app.add_css_file("custom.css")
-
-
 # -- sphinx_asdf configuration ---------------------------------------------
 
 # Top-level directory containing ASDF schemas (relative to current directory)
 asdf_schema_path = "../resources"
 # This is the prefix common to all schema IDs in this repository
 asdf_schema_standard_prefix = "schemas"
+
+
+def setup(app):
+    app.add_css_file("custom.css")

docs/index.rst

@@ -42,10 +42,3 @@ Developer Resources
 
   contributing.rst
   changes.rst
-
-Index
-=====
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`