diff --git a/.gitignore b/.gitignore index b911eff3..f782bfd6 100644 --- a/.gitignore +++ b/.gitignore @@ -132,3 +132,6 @@ dmypy.json # Ignore generated Sphinx documentation docs/source/generated/ + +# Mac OS +.DS_STORE diff --git a/CHANGES.rst b/CHANGES.rst index 0e7384c2..f9bc0f8f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -3,6 +3,7 @@ - Update reference files [#409] - Remove statement discouraging use of YAML anchors and aliases [#443] +- Documentation theme config changes for new ASDF website [#447] 1.1.1 (2024-03-06) ------------------ diff --git a/docs/source/_static/images/favicon.ico b/docs/source/_static/images/favicon.ico new file mode 100644 index 00000000..6f5eca0b Binary files /dev/null and b/docs/source/_static/images/favicon.ico differ diff --git a/docs/source/_static/images/logo-dark-mode.png b/docs/source/_static/images/logo-dark-mode.png new file mode 100644 index 00000000..275ba581 Binary files /dev/null and b/docs/source/_static/images/logo-dark-mode.png differ diff --git a/docs/source/_static/images/logo-light-mode.png b/docs/source/_static/images/logo-light-mode.png new file mode 100644 index 00000000..2d4f25c7 Binary files /dev/null and b/docs/source/_static/images/logo-light-mode.png differ diff --git a/docs/source/_static/logo.ico b/docs/source/_static/logo.ico deleted file mode 100644 index b31899f2..00000000 Binary files a/docs/source/_static/logo.ico and /dev/null differ diff --git a/docs/source/_static/logo.pdf b/docs/source/_static/logo.pdf deleted file mode 100644 index 4aedaf22..00000000 Binary files a/docs/source/_static/logo.pdf and /dev/null differ diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png deleted file mode 100644 index 63261fed..00000000 Binary files a/docs/source/_static/logo.png and /dev/null differ diff --git a/docs/source/conf.py b/docs/source/conf.py index df5df980..1a4bf6fc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -21,7 +21,7 @@ project = configuration["name"] author = f"{configuration['authors'][0]['name']} <{configuration['authors'][0]['email']}>" -copyright = f"{datetime.datetime.now().year}, {configuration['authors'][0]}" +copyright = f"{datetime.datetime.now().year}, {author}" # The short X.Y version with open(Path(__file__).parent.parent.parent / "README.md") as readme: @@ -30,14 +30,33 @@ # The full version, including alpha/beta/rc tags release = importlib.metadata.version(configuration["name"]) -intersphinx_mapping["asdf"] = ("https://asdf.readthedocs.io/en/latest/", None) # noqa: F405 +subproject_mappings = { + # Main project + "asdf-website": ("https://www.asdf-format.org/en/latest/", None), + # Subprojects + "asdf": ("https://asdf.readthedocs.io/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(subproject_mappings) # noqa: F405 # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions += ["sphinx.ext.mathjax", "sphinx.ext.ifconfig", "sphinx.ext.graphviz", "sphinx_asdf"] # noqa: F405 +additional_extensions = [ + "sphinx.ext.mathjax", + "sphinx.ext.ifconfig", + "sphinx.ext.graphviz", + "sphinx.ext.extlinks", + "sphinx_asdf", +] +extensions += additional_extensions # noqa: F405 + +# The root toctree document. +root_doc = "index" mathjax_path = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" @@ -50,9 +69,6 @@ # source_suffix = ['.rst', '.md'] source_suffix = ".rst" -# The root toctree document. -root_doc = "index" - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -61,7 +77,10 @@ language = "en" # The name of the Pygments (syntax highlighting) style to use. -# pygments_style = "sphinx" +pygments_style = "monokai" + +# NB Dark style pygments is furo-specific at this time +pygments_dark_style = "monokai" # The reST default role (used for this markup: `text`) to use for all documents. default_role = "ref" @@ -78,30 +97,41 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" - -# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -html_theme_options = {} +html_theme = "furo" # Add any paths that contain custom static files (such as style sheets) here, # 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"] +static_dir = os.path.join(os.path.dirname(__file__), "_static") # noqa: F405 + +# The root toctree document. +root_doc = "index" + +master_doc = "index" + # Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() +html_theme_path = [] + +html_additional_pages = {} # 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 = "" +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + "light_logo": "images/logo-light-mode.png", + "dark_logo": "images/logo-dark-mode.png", +} + +html_sidebars = {} # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = "%b %d, %Y" @@ -125,9 +155,18 @@ # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. html_show_copyright = True -html_context = {"bootswatch_css_custom": ["_static/asdfstandard.css"]} - - +# 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 HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. @@ -182,7 +221,7 @@ # The name of an image file (relative to this directory) to place at the top of # the title page. -latex_logo = "_static/logo.pdf" +latex_logo = "_static/images/logo-light-mode.png" # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. diff --git a/docs/source/index.rst b/docs/source/index.rst index c9751fcb..87a0a46f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,10 +3,11 @@ ASDF Standard ============= -This document describes the Advanced Scientific Data Format (ASDF), -pronounced *AZ*-diff. +This document describes the Advanced Scientific Data Format (ASDF) Standard. -The ASDF python implementation documentation can be found :ref:`here `. +The ASDF Standard prescribes the specification and implementation standards for creating, editing and reading ASDF files. + +Documentation for the `asdf` python implementation can be found :ref:`here `. .. only:: html @@ -15,7 +16,6 @@ The ASDF python implementation documentation can be found :ref:`here .. toctree:: :maxdepth: 1 - intro.rst file_layout.rst tree.rst versioning.rst @@ -47,4 +47,3 @@ published in *Astronomy and Computing*: .. only:: html * :ref:`genindex` - * :ref:`search` diff --git a/docs/source/intro.rst b/docs/source/intro.rst deleted file mode 100644 index 21e0f43e..00000000 --- a/docs/source/intro.rst +++ /dev/null @@ -1,120 +0,0 @@ -Introduction -============ - -The Flexible Image Transport System (FITS) has been the de facto -standard for storing and exchanging astronomical data for decades, but -it is beginning to show its age. Developed in the late 1970s, the -FITS authors made a number of implementation choices that, while -common at the time, are now seen to limit its utility for the needs of -modern science. As astronomy moves into a more varied set of data -product types (data models) with richer and more complex metadata, -FITS is being pushed to its breaking point. The issues with FITS are -outlined in great detail in [Thomas2015]_. - -Newer formats, such as `VOTable -`__ have partially addressed -the problem of richer, more structured metadata, by using tree -structures rather than flat key/value pairs. However, those -text-based formats are unsuitable for storing large amounts of binary -data. On the other end of the spectrum, formats such as `HDF5 -`__ and `BLZ -`__ address problems -with large data sets and distributed computing, but don't really -address the metadata needs of an interchange format. ASDF aims to -exist in the same middle ground that made FITS so successful, by being -a hybrid text and binary format: containing human editable metadata -for interchange, and raw binary data that is fast to load and use. -Unlike FITS, the metadata is highly structured and is designed -up-front for extensibility. - -ASDF has the following explicit goals: - -- It has a hierarchical metadata structure, made up of basic dynamic - data types such as strings, numbers, lists and mappings. - -- It has human-readable metadata that can be edited directly in place - in the file. - -- The structure of the data can be automatically validated using - schema. - -- It's designed for extensibility: new conventions may be used without - breaking backward compatibility with tools that do not understand - those conventions. Versioning systems are used to prevent - conflicting with alternative conventions. - -- The binary array data (when compression is not used) is a raw memory - dump, and techniques such as memory mapping can be used to - efficiently access it. - -- It is possible to read and write the file in as a stream, without - requiring random access. - -- It's built on top of industry standards, such as `YAML - `__ and `JSON Schema - `__ to take advantage of a larger - community working on the core problems of data representation. This - also makes it easier to support ASDF in new programming languages - and environments by building on top of existing libraries. - -- Since every ASDF file has the version of the specification to which - it is written, it will be possible, through careful planning, to - evolve the ASDF format over time, allowing for files that use new - features while retaining backward compatibility with older tools. - -ASDF is primarily intended as an interchange format for delivering -products from instruments to scientists or between scientists. While -it is reasonably efficient to work with and transfer, it may not be -optimal for direct use on large data sets in distributed and high -performance computing environments. That is explicitly not a goal of -the ASDF standard, as those requirements can sometimes be at odds with -the needs of an interchange format. ASDF still has a place in those -environments as a delivery mechanism, even if it ultimately is not the -actual format on which the computing is performed. - -Implementations ---------------- - -The ASDF standard is being developed concurrently with a `reference -implementation written in Python -`__. - -There are two prototype implementations for C++: `asdf-cpp -`__ and `asdf-cxx -`__. Neither is currently feature -complete, but both provide enough functionality to read and write ASDF files. - -There is also a `work-in-progress wrapper -`__ of the Python implementation -for `Julia `__. - -Incorporated standards ----------------------- - -The ASDF format is built on top of a number of existing standards: - -- `YAML 1.1 `__ - -- JSON Schema Draft 4: - - - `Core `__ - - - `Validation - `__ - - - `Hyper-Schema - `__ - -- `JSON Pointer `__ - -- `Semantic Versioning 2.0.0 `__ - -- `VOUnits (Units in the VO) - `__ - -- `Zlib Deflate compression `__ - -.. [Thomas2015] Thomas, B., Jenness. T. et al. (2015). - Learning from FITS: Limitations in use in modern astronomical research. - *Astronomy and Computing*, 12: 133-145. - `doi:10.1016/j.ascom.2015.01.009 `__ diff --git a/pyproject.toml b/pyproject.toml index 96f4642f..8f21e255 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -25,7 +25,7 @@ docs = [ 'graphviz', 'matplotlib', 'docutils', - 'sphinx-rtd-theme > 1.2.0', + 'furo', ] test = [ 'pytest', @@ -36,7 +36,7 @@ test = [ [project.urls] 'tracker' = 'https://github.com/asdf-format/asdf-standard/issues' -'documentation' = 'https://asdf-standard.readthedocs.io/en/stable' +'documentation' = 'https://www.asdf-format.org/projects/asdf-standard/en/latest' 'repository' = 'https://github.com/asdf-format/asdf-standard' [project.entry-points]