Merge pull request #61 from alphasentaurii/docs-subproject

docs/subproject-cfg
asdf-format · Dec 11, 2024 · 41cf083 · 41cf083
2 parents 4087ff9 + 88fa1ba
commit 41cf083
Show file tree

Hide file tree

Showing 11 changed files with 45 additions and 11 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,7 +1,7 @@
 0.4.0 (unreleased)
 ------------------
 
--
+- Changes documentation configuration settings to make this consistent with other asdf-related projects [#61]
 
 0.3.0 (2024-03-09)
 ------------------

diff --git a/docs/_static/images/favicon.ico b/docs/_static/images/favicon.ico
diff --git a/docs/_static/images/logo-dark-mode.png b/docs/_static/images/logo-dark-mode.png
diff --git a/docs/_static/images/logo-light-mode.png b/docs/_static/images/logo-light-mode.png
diff --git a/docs/_static/logo.ico b/docs/_static/logo.ico
diff --git a/docs/_static/logo.pdf b/docs/_static/logo.pdf
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -37,11 +37,21 @@
 # needs_sphinx = '1.2'
 
 intersphinx_mapping["pypa-packaging"] = ("https://packaging.python.org/en/latest/", None)  # noqa
-intersphinx_mapping["asdf"] = ("https://asdf.readthedocs.io/en/latest/", None)  # noqa
-intersphinx_mapping["asdf-standard"] = ("https://asdf-standard.readthedocs.io/en/latest/", None)  # noqa
 intersphinx_mapping["asdf-astropy"] = ("https://asdf-astropy.readthedocs.io/en/latest/", None)  # noqa
 intersphinx_mapping["pytest"] = ("https://docs.pytest.org/en/latest/", None)  # noqa
 
+subprojects = {
+    # main project
+    "asdf-website": ("https://www.asdf-format.org/en/latest", None),
+    # other subprojects
+    "asdf": ("https://asdf.readthedocs.io/en/latest/", 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
+
 # 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")
@@ -71,19 +81,29 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # 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 = "sphinx_rtd_theme"
+html_theme = "furo"
 html_theme_options = {}
 
 html_static_path = ["_static"]
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+# Override default settings from sphinx_asdf / sphinx_astropy (incompatible with furo)
+html_sidebars = {}
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = "_static/logo.ico"
-html_logo = "_static/logo.png"
+html_favicon = "_static/images/favicon.ico"
+html_logo = ""
+html_theme_options = {
+    "light_logo": "images/logo-light-mode.png",
+    "dark_logo": "images/logo-dark-mode.png",
+}
+
+pygments_style = "monokai"
+
+# NB Dark style pygments is furo-specific at this time
+pygments_dark_style = "monokai"
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -96,14 +116,26 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = project + "doc"
 
+# Render inheritance diagrams in SVG
+graphviz_output_format = "svg"
+
+graphviz_dot_args = [
+    "-Nfontsize=10",
+    "-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+    "-Efontsize=10",
+    "-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+    "-Gbgcolor=white",
+    "-Gfontsize=10",
+    "-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
+]
 
 # -- Options for LaTeX output --------------------------------------------------
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [("index", project + ".tex", project + " Documentation", author, "manual")]
 
-latex_logo = "_static/logo.pdf"
+latex_logo = "_static/images/logo-light.png"
 
 
 # -- Options for manual page output --------------------------------------------
@@ -113,7 +145,7 @@
 man_pages = [("index", project.lower(), project + " Documentation", [author], 1)]
 
 sys.path.insert(0, os.path.join(os.path.abspath(os.path.dirname("__file__")), "sphinxext"))
-extensions += ["sphinx_asdf"]  # noqa
+extensions += ["sphinx_asdf", "sphinx.ext.intersphinx", "sphinx.ext.extlinks"]  # noqa
 
 
 def setup(app):

diff --git a/pyproject.toml b/pyproject.toml
@@ -32,7 +32,7 @@ docs = [
     'graphviz',
     'matplotlib',
     'docutils',
-    'sphinx-rtd-theme',
+    'furo',
 ]
 test = [
     'pytest',
@@ -41,7 +41,7 @@ test = [
 
 [project.urls]
 'tracker' = 'https://github.com/asdf-format/asdf-coordinates-schemas/issues'
-'documentation' = 'https://asdf-coordinates-schemas.readthedocs.io/en/latest/'
+'documentation' = 'https://www.asdf-format.org/projects/asdf-coordinates-schemas/en/latest/'
 'repository' = 'https://github.com/asdf-format/asdf-coordinates-schemas'
 
 [project.entry-points]

diff --git a/tests/test_integration.py b/tests/test_integration.py
@@ -1,6 +1,7 @@
 """
 Test that the asdf library integration is working properly.
 """
+
 from pathlib import Path
 
 import asdf

diff --git a/tests/test_manifests.py b/tests/test_manifests.py
@@ -2,6 +2,7 @@
 Test that the manifest file is correctly structured and refers
 to schemas that exist.
 """
+
 from pathlib import Path
 
 import asdf