From 42d21c79c3196ce5610a905e73e502d2da9cb8e8 Mon Sep 17 00:00:00 2001 From: Laurie O Date: Mon, 11 Dec 2023 10:53:19 +1000 Subject: [PATCH] Convert attributes in HTML spec into API-docs --- .../specifications/simple-repository-api.rst | 42 +++++++++---------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst index 69bc02833..b6f6e5c5c 100644 --- a/source/specifications/simple-repository-api.rst +++ b/source/specifications/simple-repository-api.rst @@ -159,12 +159,11 @@ A `metadata element`_ ```` may exist anywhere in the HTML document, with implements. Each project provided by the index has a corresponding `anchor element`_ -````: +````, whose body text must exist and is the name of the project (not +necessarily :ref:`normalized `). This element has +attributes: -* Its body text must exist and is the name of the project (not necessarily - :ref:`normalized `). - -* Its ``href`` attribute must exist and is a URL to the :ref:`project details +* ``href`` (required) - the value is a URL to the :ref:`project details ` page for the project. This URL must end with a forward-slash ``/``, but may be absolute or relative. @@ -282,35 +281,34 @@ A `metadata element`_ ```` may exist anywhere in the HTML document, with implements. Each distribution package file provided by the index for the project has a -corresponding `anchor element`_ ````: - -* Its body text must exist and is the file's filename. +corresponding `anchor element`_ ````, whose body text must exist and be the +file's filename. This element has attributes: -* Its ``href`` attribute must exist and is the file's URL. +* ``href`` (required) - attribute must exist and is the file's URL. * This URL should also include a URL fragment of the form ``#=``, where ```` is the hash name and ```` is hash value. -* A ``data-gpg-sig`` `data attribute`_ may exist, and have value ``true`` to - indicate a file has a GPG signature (at the location described above), or +* ``data-gpg-sig`` (optional) - a `data attribute`_, which has value ``true`` + to indicate a file has a GPG signature (at the location described above), or ``false`` to indicate no signature. Indexes should do this for none or all files (not some). -* A ``data-requires-python`` `data attribute`_ may exist, and have value equal - to the :ref:`core-metadata-requires-python` metadata field for the file's - release, with HTML-encoding (less-than ``<`` becomes the string ``<``, and +* ``data-requires-python`` (optional) - a `data attribute`_, whose value is the + :ref:`core-metadata-requires-python` metadata field for the file's release, + with HTML-encoding (less-than ``<`` becomes the string ``<``, and greater-than ``>`` becomes the string ``>``). -* A ``data-yanked`` `data attribute`_ may exist to indicate the file was - :ref:`yanked `. The attribute may have a value which - specifies the reason the file is yanked. +* ``data-yanked`` (optional) - a `data attribute`_, whose existence indicates + the file was :ref:`yanked `. The attribute may have a + value which specifies the reason the file was yanked. -* A ``data-core-metadata`` `data attribute`_ may exist to indicate the index - provides the file's core-metadata. The attribute's value should be of the - form ``=``, where ```` is the hash name and ```` is - hash value; otherwise, the value may the string ``true``, or not provided, if - the metadata's hash is not available. +* ``data-core-metadata`` (optional) - a `data attribute`_, whose existence + indicates the index provides the file's core-metadata. The attribute's value + should be of the form ``=``, where ```` is the hash name + and ```` is hash value; otherwise, the value may the string ``true``, + or not provided, if the metadata's hash is not available. This attribute may be duplicated as the `data attribute`_ ``data-dist-info-metadata``.