diff --git a/changes/1897.doc.rst b/changes/1897.doc.rst new file mode 100644 index 000000000..addbd4343 --- /dev/null +++ b/changes/1897.doc.rst @@ -0,0 +1 @@ +updates docs theme to be consistent with asdf subprojects diff --git a/docs/_static/css/globalnav.css b/docs/_static/css/globalnav.css new file mode 100644 index 000000000..66bc56f6f --- /dev/null +++ b/docs/_static/css/globalnav.css @@ -0,0 +1,9 @@ +/* Top Banner Navigation +-------------------------------------------------- */ +.announcement-content a { + padding-right: 1em; + } + +.announcement-content a:hover { + color: fuchsia; +} diff --git a/docs/_static/images/favicon.ico b/docs/_static/images/favicon.ico new file mode 100644 index 000000000..2d4f25c72 Binary files /dev/null and b/docs/_static/images/favicon.ico differ diff --git a/docs/_static/images/logo-dark-mode.png b/docs/_static/images/logo-dark-mode.png new file mode 100644 index 000000000..275ba581f Binary files /dev/null and b/docs/_static/images/logo-dark-mode.png differ diff --git a/docs/_static/images/logo-light-mode.png b/docs/_static/images/logo-light-mode.png new file mode 100644 index 000000000..2d4f25c72 Binary files /dev/null and b/docs/_static/images/logo-light-mode.png differ diff --git a/docs/_static/logo.ico b/docs/_static/logo.ico deleted file mode 100644 index b31899f2c..000000000 Binary files a/docs/_static/logo.ico and /dev/null differ diff --git a/docs/_static/logo.pdf b/docs/_static/logo.pdf deleted file mode 100644 index 4aedaf22c..000000000 Binary files a/docs/_static/logo.pdf and /dev/null differ diff --git a/docs/_static/logo.png b/docs/_static/logo.png deleted file mode 100644 index 63261feda..000000000 Binary files a/docs/_static/logo.png and /dev/null differ diff --git a/docs/asdf/arrays.rst b/docs/asdf/arrays.rst index 4a1a6843e..1af3e791e 100644 --- a/docs/asdf/arrays.rst +++ b/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 diff --git a/docs/asdf/features.rst b/docs/asdf/features.rst index fe3a39c47..0ceae8f07 100644 --- a/docs/asdf/features.rst +++ b/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. diff --git a/docs/asdf/user_api/asdf_config.rst b/docs/asdf/user_api/asdf_config.rst new file mode 100644 index 000000000..38eb576c1 --- /dev/null +++ b/docs/asdf/user_api/asdf_config.rst @@ -0,0 +1,7 @@ +****************** +asdf.config Module +****************** + +.. currentmodule:: asdf + +.. automodapi:: asdf.config diff --git a/docs/asdf/user_api.rst b/docs/asdf/user_api/asdf_package.rst similarity index 59% rename from docs/asdf/user_api.rst rename to docs/asdf/user_api/asdf_package.rst index 214d3de18..64a9eae46 100644 --- a/docs/asdf/user_api.rst +++ b/docs/asdf/user_api/asdf_package.rst @@ -1,8 +1,8 @@ -.. _user_api: +************ +asdf Package +************ -******** -User API -******** +.. currentmodule:: asdf .. automodapi:: asdf :include-all-objects: @@ -10,7 +10,3 @@ User API :no-inheritance-diagram: :skip: ValidationError :skip: Stream - -.. automodapi:: asdf.search - -.. automodapi:: asdf.config diff --git a/docs/asdf/user_api/asdf_search.rst b/docs/asdf/user_api/asdf_search.rst new file mode 100644 index 000000000..a0cd0dcd7 --- /dev/null +++ b/docs/asdf/user_api/asdf_search.rst @@ -0,0 +1,7 @@ +****************** +asdf.search Module +****************** + +.. currentmodule:: asdf + +.. automodapi:: asdf.search diff --git a/docs/asdf/user_api/index.rst b/docs/asdf/user_api/index.rst new file mode 100644 index 000000000..aa1263c8d --- /dev/null +++ b/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 ` +* :doc:`asdf.search Module ` +* :doc:`asdf.config Module ` diff --git a/docs/asdf/using_extensions.rst b/docs/asdf/using_extensions.rst index 5461a66e7..1de72b7b2 100644 --- a/docs/asdf/using_extensions.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index f4877acba..0d5890dba 100644 --- a/docs/conf.py +++ b/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"{text}" + +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") diff --git a/docs/index.rst b/docs/index.rst index 6714a0586..b72e8eb0f 100644 --- a/docs/index.rst +++ b/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` diff --git a/docs/rtd_environment.yaml b/docs/rtd_environment.yaml index 6e6bfa6a3..31aa96589 100644 --- a/docs/rtd_environment.yaml +++ b/docs/rtd_environment.yaml @@ -6,5 +6,5 @@ dependencies: - python=3.11 - pip - graphviz - - sphinx_rtd_theme>1.2.0 + - furo - towncrier diff --git a/pyproject.toml b/pyproject.toml index 785276fb4..89f4f4c81 100644 --- a/pyproject.toml +++ b/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]