From af4995ab9870b09d2ba676e54fa68b5828781d70 Mon Sep 17 00:00:00 2001 From: Matthew Evans <7916000+ml-evs@users.noreply.github.com> Date: Thu, 4 Apr 2024 16:40:47 +0100 Subject: [PATCH] Final formatting fixes (#511) * Remove erroneously escaped underscores inside rst roles * Fix indentation level of some blocks * Change some single backtick quotes. (#513) --------- Co-authored-by: Antanas Vaitkus --- optimade.rst | 110 +++++++++++++++++++++++++-------------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/optimade.rst b/optimade.rst index b2f37d25..678ee90f 100644 --- a/optimade.rst +++ b/optimade.rst @@ -471,7 +471,7 @@ When an implementation receives a request with a query filter that refers to an The rationale for treating properties from other databases as unknown rather than triggering an error is for OPTIMADE to support queries using database-specific properties that can be sent to multiple databases. -For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors: +For example, the following query can be sent to API implementations ``exmpl1`` and ``exmpl2`` without generating any errors: :filter:`filter=_exmpl1_band_gap<2.0 OR _exmpl2_band_gap<2.5` @@ -1040,7 +1040,7 @@ The API implementation MAY provide other entry types than the ones standardized Such entry types MUST be prefixed by a database-provider-specific prefix (i.e., the resource objects' :property:`type` value should start with the database-provider-specific prefix, e.g., :property:`type` = :val:`_exmpl_workflows`). Each custom entry type SHOULD be served at a corresponding entry listing endpoint under the versioned or unversioned base URL that serves the API with the same name (i.e., equal to the resource objects' :property:`type` value, e.g., :endpoint:`/_exmpl_workflows`). It is RECOMMENDED to align with the OPTIMADE API specification practice of using a plural for entry resource types and entry type endpoints. -Any custom entry listing endpoint MUST also be added to the :property:`available\_endpoints` and :property:`entry\_types\_by\_format` attributes of the `Base Info Endpoint`_. +Any custom entry listing endpoint MUST also be added to the :property:`available_endpoints` and :property:`entry_types_by_format` attributes of the `Base Info Endpoint`_. For more on custom endpoints, see `Custom Extension Endpoints`_. @@ -1125,7 +1125,7 @@ Examples: - :query-url:`http://example.com/optimade/v1/structures?_exmpl_key=A3242DSFJFEJE` - :query-url:`http://example.com/optimade/v1/structures?_exmpl_warning_verbosity=10` -- :query-url:`http://example.com/optimade/v1/structures?\_exmpl\_filter="elements all in [Al, Si, Ga]"` +- :query-url:`http://example.com/optimade/v1/structures?_exmpl_filter="elements all in [Al, Si, Ga]"` **Note**: the specification presently makes no attempt to standardize access control mechanisms. There are security concerns with access control based on URL tokens, and the above example is not to be taken as a recommendation for such a mechanism. @@ -1139,7 +1139,7 @@ In the default JSON response format every dictionary (`resource object `__ (see, e.g., rdfs:label). + The name and label fields ensure implementations will be able to give meaningful names to definitions if they are translated into other formats with various requirements on human-readable names, e.g., as `RDF data `__ (see, e.g., rdfs:label). - **OPTIONAL keys:** +**OPTIONAL keys:** - - :field:`version`: String. - This string indicates the version of the definition. - The string SHOULD be in the format described by the `semantic versioning v2 `__ standard. - When a definition is changed in a way that consitutes a redefinition it SHOULD indicate this by incrementing the MAJOR version number. +- :field:`version`: String. + This string indicates the version of the definition. + The string SHOULD be in the format described by the `semantic versioning v2 `__ standard. + When a definition is changed in a way that consitutes a redefinition it SHOULD indicate this by incrementing the MAJOR version number. - - :field:`resources`: List. - A list of dictionaries that references remote resources that describe the property. - The format of each dictionary is: +- :field:`resources`: List. + A list of dictionaries that references remote resources that describe the property. + The format of each dictionary is: - **REQUIRED keys:** + **REQUIRED keys:** - - :field:`relation`: String. - A human-readable description of the relationship between the property and the remote resource, e.g., a "natural language description". + - :field:`relation`: String. + A human-readable description of the relationship between the property and the remote resource, e.g., a "natural language description". - - :field:`resource-id`: String. - An IRI of the external resource, which MAY be a resolvable URL. + - :field:`resource-id`: String. + An IRI of the external resource, which MAY be a resolvable URL. **REQUIRED keys for all levels of the Property Definition:** @@ -2181,15 +2181,15 @@ A Property Definition MUST be composed according to the combination of the requi **REQUIRED keys:** - - :field:`names`: List of Strings. - A list of names of the dimensions of the underlying one or multi-dimensionsional data represented as mutiple levels of lists. - The order is that the the first name applies to the outermost list, the next name to the lists embedded in that list, etc. + - :field:`names`: List of Strings. + A list of names of the dimensions of the underlying one or multi-dimensionsional data represented as mutiple levels of lists. + The order is that the the first name applies to the outermost list, the next name to the lists embedded in that list, etc. - - :field:`sizes`: List of Integers or :val:`null`. - A list of fixed length requirements on the underlying one or multi-dimensionsional data represented as mutiple levels of lists. - The order is that the the first name applies to the outermost list, the next name to the lists embedded in that list, etc. - The data only validates if the respective level consists of lists of exactly this length. - A value of `null` allows arbitrary-length lists at the corresponding level. + - :field:`sizes`: List of Integers or :val:`null`. + A list of fixed length requirements on the underlying one or multi-dimensionsional data represented as mutiple levels of lists. + The order is that the the first name applies to the outermost list, the next name to the lists embedded in that list, etc. + The data only validates if the respective level consists of lists of exactly this length. + A value of :val:`null` allows arbitrary-length lists at the corresponding level. Note: OPTIMADE Property Definitions use this field, and MUST NOT use the JSON Schema validating fields minItems and maxItems since that would require reprocessing the schema to handle requests using the OPTIMADE features that requests partial data in lists. Instead, the length of lists can be validated against the length information provided in the :field:`sizes` subfield of :field:`x-optimade-dimensions` (which, at this time, can only specify a fixed length requirement.) @@ -2587,8 +2587,8 @@ An OPTIMADE Physical Unit Definition is a dictionary adhering to the following f - :field:`symbol`: String. The symbol to use from the referenced standard, expressed according to that standard. The field MAY use mathematical expressions written the same way as described in the `definition of the description field`_. - This field MAY be different from the symbol being defined via the definition if the unit will be referenced in `x-optimade-unit` fields using a different symbol than the one used in the standard or if the symbol is expressed in the standard in a way that requires mathematical notation. - However, if possible, the `symbol` fields SHOULD be the same. + This field MAY be different from the symbol being defined via the definition if the unit will be referenced in :field:`x-optimade-unit` field using a different symbol than the one used in the standard or if the symbol is expressed in the standard in a way that requires mathematical notation. + However, if possible, the :field:`symbol` field SHOULD be the same. **OPTIONAL keys:** @@ -2674,7 +2674,7 @@ An OPTIMADE Physical Unit Definition is a dictionary adhering to the following f A dictionary specifying the offset value, adhering to the same format as :field:`scale`. If omitted or :val:`null`, the defaults for the :field:`numerator`, :field:`denominator`, and :field:`exponent` are respectively 0, 1, and 0. - If the fields in :field:`scale` are designated as `sn`, `sd`, and `se`; and the fields in :field:`offset` are designated as ``on``, ``od``, and ``oe``; and :field:`base-units-expression` is designated as ``b``, these fields state the following defining relation: a value ``v`` multiplied by the unit being defined is equal to the following expression ``(v * (sn/sd) * 10**se + (on/od) * 10**oe)*b``, where ``*`` designates multiplication and ``**`` designates exponentiation. + If the fields in :field:`scale` are designated as ``sn``, ``sd``, and ``se``; and the fields in :field:`offset` are designated as ``on``, ``od``, and ``oe``; and :field:`base-units-expression` is designated as ``b``, these fields state the following defining relation: a value ``v`` multiplied by the unit being defined is equal to the following expression ``(v * (sn/sd) * 10**se + (on/od) * 10**oe)*b``, where ``*`` designates multiplication and ``**`` designates exponentiation. For example, the defining relation of the temperature unit Fahrenheit ``F`` in Celsius ``C``, that says that ``x F = (x - 32) * (5/9) C = 5/9 x + (-160/9) C`` could be expressed as follows: .. code:: jsonc @@ -2813,7 +2813,7 @@ type - **Query**: MUST be a queryable property with support for all mandatory filter features. - **Response**: REQUIRED in the response. - MUST be an existing entry type. - - The entry of type `` and ID `` MUST be returned in response to a request for :endpoint:`//` under the versioned or unversioned base URL serving the API. + - The entry of type ```` and ID ```` MUST be returned in response to a request for :endpoint:`//` under the versioned or unversioned base URL serving the API. - **Examples**: @@ -2869,7 +2869,7 @@ Custom properties - These MUST be prefixed by a database-provider-specific prefix (see appendix `Namespace Prefixes`_). - Implementations MUST add the properties to the list of :property:`properties` under the respective entry listing :endpoint:`info` endpoint (see `Entry Listing Info Endpoints`_). -- **Examples**: A few examples of valid database-provided-specific property names, for a predefined prefix `_exmpl`, are as follows: +- **Examples**: A few examples of valid database-provided-specific property names, for a predefined prefix ``_exmpl``, are as follows: - :property:`_exmpl_formula_sum` - :property:`_exmpl_band_gap` @@ -3154,7 +3154,7 @@ space\_group\_symmetry\_operations\_xyz - Space group operations for the space group with ITC number 3 (H-M symbol :val:`P 2`, extended H-M symbol :val:`P 1 2 1`, Hall symbol :val:`P 2y`): :val:`["x,y,z", "-x,y,-z"]` - Space group operations for the space group with ITC number 5 (H-M symbol :val:`C 2`, extended H-M symbol :val:`C 1 2 1`, Hall symbol :val:`C 2y`): :val:`["x,y,z", "-x,y,-z", "x+1/2,y+1/2,z", "-x+1/2,y+1/2,-z"]` -- **Notes:** The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the :property:`lattice\_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material. +- **Notes:** The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the :property:`lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material. Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension. This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry. @@ -3240,7 +3240,7 @@ space\_group\_symbol\_hermann\_mauguin\_extended - The change-of-basis operation SHOULD be provided for the non-standard axis and cell choices. - The extended H-M symbol does not unambiguously communicate the origin choice, and the given symbol SHOULD NOT be amended to convey this information. - The description of the change-of-basis SHOULD follow conventions of the ITC Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001). - - The same character string encoding conventions MUST be used as for the specification of the :property:`space\_group\_symbol\_hermann\_mauguin` property. + - The same character string encoding conventions MUST be used as for the specification of the :property:`space_group_symbol_hermann_mauguin` property. - **Examples**: @@ -3608,13 +3608,13 @@ url url\_stable\_until ~~~~~~~~~~~~~~~~~~ -- **Description**: Point in time until which the URL in `url` is guaranteed to stay stable. +- **Description**: Point in time until which the URL in :property:`url` is guaranteed to stay stable. - **Type**: timestamp - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - **Query**: Support for queries on this property is OPTIONAL. - - :val:`null` means that there is no stability guarantee for the URL in `url`. + - :val:`null` means that there is no stability guarantee for the URL in :property:`url`. Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`. name @@ -4095,7 +4095,7 @@ The strings below contain Extended Regular Expressions (EREs) to recognize ident The Symmetry Operation String Regular Expressions ------------------------------------------------- -Symmetry operation strings that comprise the :property:`space\_group\_symmetry\_operations\_xyz` property MUST conform to the following regular expressions. +Symmetry operation strings that comprise the :property:`space_group_symmetry_operations_xyz` property MUST conform to the following regular expressions. The regular expressions are recorded below in two forms, one in a more readable form using variables and the other as an explicit pattern compatible with the `OPTIMADE Regular Expression Format`_. - Perl Compatible Regular Expression (PCRE) syntax, with `Perl extensions `__ used for readability and expressivity.