Merge pull request #1897 from alphasentaurii/docs-theme-updates

docs/theme-updates

changes/1897.doc.rst

@@ -0,0 +1 @@
+updates docs theme to be consistent with asdf subprojects

docs/_static/css/globalnav.css

@@ -0,0 +1,9 @@
+/* Top Banner Navigation
+-------------------------------------------------- */
+.announcement-content a {
+    padding-right: 1em;
+  }
+
+.announcement-content a:hover {
+  color: fuchsia;
+}

docs/asdf/arrays.rst

@@ -1,7 +1,12 @@
 .. currentmodule:: asdf
 
+**********
+Array Data
+**********
+
+
 Saving arrays
--------------
+=============
 
 Beyond the basic data types of dictionaries, lists, strings and numbers, the
 most important thing ASDF can save is arrays.  It's as simple as putting a
@@ -29,8 +34,9 @@ the array, but the actual array content is in a binary block.
 
 .. asdf:: test.asdf
 
+
 Sharing of data
----------------
+===============
 
 Arrays that are views on the same data automatically share the same
 data in the file.  In this example an array and a subview on that same
@@ -60,7 +66,7 @@ a specific array.
 .. asdf:: test.asdf
 
 Saving inline arrays
---------------------
+====================
 
 For small arrays, you may not care about the efficiency of a binary
 representation and just want to save the array contents directly in the YAML
@@ -104,7 +110,7 @@ see :ref:`config_options_array_inline_threshold`.
 .. _exploded:
 
 Saving external arrays
-----------------------
+======================
 
 ASDF files may also be saved in "exploded form", which creates multiple files
 corresponding to the following data items:
@@ -152,7 +158,7 @@ To save a block in an external file, set its block type to
 .. asdf:: test0000.asdf
 
 Streaming array data
---------------------
+====================
 
 In certain scenarios, you may want to stream data to disk, rather than
 writing an entire array of data at once.  For example, it may not be
@@ -224,7 +230,7 @@ to numpy arrays stored in ASDF:
                 fd.write(array.tobytes())
 
 Compression
------------
+===========
 
 Individual blocks in an ASDF file may be compressed.
 
@@ -271,7 +277,7 @@ different compression algorithm when writing the file out again.
     af.write_to('different.asdf', all_array_compression='lz4')
 
 Memory mapping
---------------
+==============
 
 By default, all internal array data is memory mapped using `numpy.memmap`. This
 allows for the efficient use of memory even when reading files with very large

docs/asdf/features.rst

@@ -4,6 +4,7 @@
 Core Features
 *************
 
+
 This section discusses the core features of the ASDF data format, and provides
 examples and use cases that are specific to the Python implementation.
 

docs/asdf/user_api/asdf_config.rst

@@ -0,0 +1,7 @@
+******************
+asdf.config Module
+******************
+
+.. currentmodule:: asdf
+
+.. automodapi:: asdf.config

docs/asdf/user_api.rst → docs/asdf/user_api/asdf_package.rst

@@ -1,16 +1,12 @@
-.. _user_api:
+************
+asdf Package
+************
 
-********
-User API
-********
+.. currentmodule:: asdf
 
 .. automodapi:: asdf
     :include-all-objects:
     :inherited-members:
     :no-inheritance-diagram:
     :skip: ValidationError
     :skip: Stream
-
-.. automodapi:: asdf.search
-
-.. automodapi:: asdf.config

docs/asdf/user_api/asdf_search.rst

@@ -0,0 +1,7 @@
+******************
+asdf.search Module
+******************
+
+.. currentmodule:: asdf
+
+.. automodapi:: asdf.search

docs/asdf/user_api/index.rst

@@ -0,0 +1,17 @@
+.. _user_api:
+
+********
+User API
+********
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    asdf_package.rst
+    asdf_search.rst
+    asdf_config.rst
+
+* :doc:`asdf Package <asdf_package>`
+* :doc:`asdf.search Module <asdf_search>`
+* :doc:`asdf.config Module <asdf_config>`

docs/asdf/using_extensions.rst

@@ -1,7 +1,12 @@
 .. currentmodule:: asdf
 
+****************
+Using Extensions
+****************
+
+
 The built-in extension
-----------------------
+======================
 
 The ability to serialize the following types is provided by `asdf`'s built-in
 extension:
@@ -21,7 +26,7 @@ its implementation. However, it is useful to be aware that the built-in
 extension is always in effect when reading and writing ASDF files.
 
 Custom types
-------------
+============
 
 For the purposes of this documentation, a "custom type" is any data type that
 can not be serialized by the built-in extension.
@@ -43,7 +48,7 @@ The version number will increase whenever a schema (and therefore the converter
 implementation) changes.
 
 Extensions
-----------
+==========
 
 In order for the converters and schemas to be used by `asdf`, they must be
 packaged into an **extension** class. In general, the details of extensions are
@@ -58,7 +63,7 @@ always used). There are two ways to use custom extensions, which are detailed
 below in :ref:`other_packages` and :ref:`explicit_extensions`.
 
 Writing custom types to files
-*****************************
+-----------------------------
 
 `asdf` is not capable of serializing any custom type unless an extension is
 provided that defines how to serialize that type. Attempting to do so will
@@ -68,7 +73,7 @@ for custom types and extensions, see :ref:`extending_extensions`.
 .. _reading_custom_types:
 
 Reading files with custom types
-*******************************
+-------------------------------
 
 The `asdf` software is capable of reading files that contain custom data types
 even if the extension that was used to create the file is not present. However,
@@ -93,7 +98,7 @@ that are required for instantiating custom types when reading ASDF files.
 .. _custom_type_versions:
 
 Custom types, extensions, and versioning
-----------------------------------------
+========================================
 
 Tags and schemas that follow best practices are versioned. This allows changes
 to tags and schemas to be recorded, and it allows `asdf` to define behavior with
@@ -108,7 +113,7 @@ Since ASDF is designed to be an archival file format, extension authors are
 encouraged to maintain backwards compatibility with all older tag versions.
 
 Reading files
-*************
+-------------
 
 When `asdf` encounters a tagged object in a file, it will compare the URI of
 the tag in the file with the list of tags handled by available converters.
@@ -121,7 +126,7 @@ found by the library will be used.  Users may disable a converter by removing
 its extension with the `~asdf.config.AsdfConfig.remove_extension` method.
 
 Writing files
-*************
+-------------
 
 When writing a object to a file, `asdf` compares the object's type to the list
 of types handled by available converters.  The first matching converter will
@@ -135,7 +140,7 @@ its extension with the `~asdf.config.AsdfConfig.remove_extension` method.
 .. _other_packages:
 
 Extensions from other packages
-------------------------------
+==============================
 
 Some external packages may define extensions that allow `asdf` to recognize some
 or all of the types that are defined by that package. Such packages may install
@@ -163,7 +168,7 @@ other extensions from other packages, depending on what is installed.
 .. _explicit_extensions:
 
 Explicit use of extensions
---------------------------
+==========================
 
 Sometimes no packaged extensions are provided for the types you wish to
 serialize. In this case, it is necessary to explicitly install any necessary
@@ -207,7 +212,7 @@ To read the file (in a new session) we again need to install the extension first
 .. _extension_checking:
 
 Extension checking
-------------------
+==================
 
 When writing ASDF files using this software, metadata about the extensions that
 were used to create the file will be added to the file itself.  This includes

docs/conf.py

@@ -28,7 +28,7 @@
 # -- Project information ------------------------------------------------------
 project = configuration["name"]
 author = f"{configuration['authors'][0]['name']} <{configuration['authors'][0]['email']}>"
-copyright = f"{datetime.datetime.now().year}, {configuration['authors'][0]['name']}"
+copyright = f"{datetime.datetime.now().year}, {author}"
 
 release = distribution(configuration["name"]).version
 # for example take major/minor
@@ -63,4 +63,73 @@
 intersphinx_mapping["stdatamodels"] = ("https://stdatamodels.readthedocs.io/en/latest/", None)
 intersphinx_mapping["pytest"] = ("https://docs.pytest.org/en/latest/", None)
 
-extensions += ["sphinx_inline_tabs"]
+# Docs are hosted as a "subproject" under the main project's domain: https://www.asdf-format.org/projects
+# This requires including links to main project (asdf-website) and the other asdf subprojects
+# See https://docs.readthedocs.io/en/stable/guides/intersphinx.html#using-intersphinx
+subprojects = {
+    # main project
+    "asdf-website": ("https://www.asdf-format.org/en/latest", None),
+    # other subprojects
+    "asdf-standard": ("https://www.asdf-format.org/projects/asdf-standard/en/latest/", None),
+    "asdf-coordinates-schemas": ("https://www.asdf-format.org/projects/asdf-coordinates-schemas/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: F405
+
+extensions += ["sphinx_inline_tabs", "sphinx.ext.intersphinx", "sphinx.ext.extlinks"]  # noqa: F405
+
+html_theme = "furo"
+html_static_path = ["_static"]
+# 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/images/favicon.ico"
+html_logo = ""
+
+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>"
+
+html_theme_options = {
+    "light_logo": "images/logo-light-mode.png",
+    "dark_logo": "images/logo-dark-mode.png",
+    "announcement": topbanner,
+}
+
+pygments_style = "monokai"
+# NB Dark style pygments is furo-specific at this time
+pygments_dark_style = "monokai"
+# 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/images/logo-light-mode.png"
+
+
+def setup(app):
+    app.add_css_file("css/globalnav.css")

docs/index.rst

@@ -67,7 +67,7 @@ API Documentation
 .. toctree::
   :maxdepth: 1
 
-  asdf/user_api
+  asdf/user_api/index
   asdf/developer_api
 
 Developer Overview
@@ -108,4 +108,3 @@ Index
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

docs/rtd_environment.yaml

@@ -6,5 +6,5 @@ dependencies:
   - python=3.11
   - pip
   - graphviz
-  - sphinx_rtd_theme>1.2.0
+  - furo
   - towncrier

pyproject.toml

@@ -40,6 +40,7 @@ docs = [
   "graphviz",
   "sphinx-inline-tabs",
   'tomli; python_version < "3.11"',
+  "furo",
 ]
 tests = [
   "fsspec[http]>=2022.8.2",
@@ -49,7 +50,7 @@ tests = [
   "pytest-remotedata",
 ]
 [project.urls]
-'documentation' = 'https://asdf.readthedocs.io/en/stable'
+'documentation' = 'https://asdf.readthedocs.io/en/stable/'
 'repository' = 'https://github.com/asdf-format/asdf'
 'tracker' = 'https://github.com/asdf-format/asdf/issues'
 [project.entry-points]