139 custom theme

[duncandewhurst]

Related issues

• Create a better looking documentation site #139

Description

TO-DO:

• Fix build error
• Make JSON examples collapsible
• Fix styling of docson in dark mode

Merge checklist

• Update the changelog (style guide)
• Run ./manage.py pre-commit to update derivative schema files, reference documentation and examples

If there are changes to network-schema.json, network-package-schema.json, reference/publication_formats/json.md, reference/publication_formats/geojson.md or guidance/publication.md#how-to-publish-large-networks, update the relevant manually authored examples:

• examples/json/:
  • network-package.json
  • api-response.json
  • multiple-networks.json
  • network-embedded.json
  • network-separate-endpoints.json
  • network-separate-files.json
  • nodes-endpoint.json
  • spans-endpoint.json
• examples/geojson/:
  • api-response.geojson
  • multiple-networks.geojson

If you used a validation keyword, type or format that is not already used in the schema:

• Update the list of validation keywords, types or formats in JSON Schema usage.
• Add a field that fails validation against the new keyword, type or format to network-package-invalid.json.
• Check that OFDS CoVE reports an appropriate validation error.

If you added a normative rule that is not encoded in JSON Schema:

• Update the list of other normative rules.
• Add a field that does not conform to the rule to network-package-additional-checks.json.
• Open a new issue to add an additional check to Lib Cove OFDS.

If there are changes to examples/geojson/nodes.geojson or examples/geojson/spans.geojson, check and update the data use examples:

• examples/leaflet/leaflet.ipynb
• examples/qgis/geojson.qgs

[lgs85]

I wonder if we can also update how the reference tables are formatted? The existing approach, which uses two rows per object, is very confusing in my opinion:

Title	Description	Type	Format	Required
id		string	uuid	Required
Identifier	A universally unique identifier for this network, as defined by RFC 4122. For more information, see the identifier reference.
name		string
Network name	A name for this network.
nodes		array[Node]
Nodes	Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless: The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in .links The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in .links. For more information, see how to format data for publication. See Node

In addition to the structural issue, I'm not convinced about the utility of title. Something like this is clearer I think:

Field	Description	Type	Format	Required
id	A universally unique identifier for this network, as defined by RFC 4122. For more information, see the identifier reference.	string	uuid	Required
name	A name for this network.	string
nodes	Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless: The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in .links The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in .links. For more information, see how to format data for publication. See Node	array[Node]

If we want to keep title, it could look like this, though this is a little unweildy:

Field	Title	Description	Type	Format	Required
id	Identifier	A universally unique identifier for this network, as defined by RFC 4122. For more information, see the identifier reference.	string	uuid	Required
name	Network name	A name for this network.	string
nodes	Nodes	Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless: The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in .links The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in .links. For more information, see how to format data for publication. See Node	array[Node]

[duncandewhurst]

Thanks, @lgs85. My understanding is that the table layout (structure of rows and columns) is controlled by https://github.com/OpenDataServices/sphinxcontrib-opendataservices-jsonschema whilst only the formatting (colours, borders etc.) is controlled by the theme. As such, I've created an issue in that repository with your feedback.

[duncandewhurst]

@Bjwebb, I'm trying to get a customised version of the Furo theme working. I think I'm basically there, but the collapsing of JSON include directives seems to be missing (example). Do you know what I need to do get that working?

[Bjwebb]

We add some extra css and js files at https://github.com/Open-Telecoms-Data/open-fibre-data-standard/blob/4e1abb85ecaa040c9c1a8427a1c889cbd5e7ad0c/docs/_templates/layout.html (for the collapsing the relevant one is renderjson).

Furo doesn't support including them like that. According to the furo docs you need to add the custom files in the conf.py instead.

Does that look like something you could follow, or would you like me to make the change?