In at least these listed, the worked examples are hard-coded into the documentation files as markdown or rst formatted tables. e.g. in /docs/hsds/classifications.md.
### services
+-------+-------------+-------------------+
| id | name | description |
+-------+-------------+-------------------+
| 89652 | Kitten Time | Time with kittens |
+-------+-------------+-------------------+
| 89654 | Puppy Time | Time with puppies |
+-------+-------------+-------------------+
At the same time, the Schema Reference page contains examples (e.g. this which are not hard-coded, instead being imported from externally managed files.
E.g.
.. jsoninclude:: ../../examples/service_full.json
:jsonpointer:
:title: service
I think this approach should be replicated across non-normative guidance:
fewer chances for formatting mistakes – as much as I love markdown and rst, the table formatting is pretty dire and requires either a separate tool/plugin to make nice tables to copy and paste into docs, or alternatively a lot of keypresses and aligning things. It's also unsuitable for longer/larger tables with lots of rows and columns. Using Sphinx's built-in CSV table renderer, we can manage the examples in CSV files whicha re much friendlier to work with either in a text editor or a spreadsheet and then these can be imported to the docs.
separation of concerns – related to above. Someone contributing to the docs for the first time has less chance of messing up the examples. If we just want to update an example without the surrounding text, we can just edit the example file and Sphinx will take care of the rest.
faster to produce new examples – again because we're not having to manually format markdown or RST tables.
Can begin to use JSON examples – HSDS 3.0 is a JSON formatted standard, so we should probably provide examples in JSON. These will require importing as well, so we can lay the groundwork for this early.
I believe that the current top-level examples folder is managed by the schema tooling, so would be inappropriate. I recommend we create docs/hsds/examples/ as a folder for non-normative or documentation-specific examples, and then create sub-folders for each topic. This approach is seen elsewhere such as in Open Contracting.
Emergent from #425.
Some of the non-normative guidance contains some worked examples on various topics and pages e.g. on the Classifications, Attributes, and Taxonomies page and on the Schedules page.
In at least these listed, the worked examples are hard-coded into the documentation files as markdown or rst formatted tables. e.g. in
/docs/hsds/classifications.md
.At the same time, the Schema Reference page contains examples (e.g. this which are not hard-coded, instead being imported from externally managed files.
E.g.
I think this approach should be replicated across non-normative guidance:
I believe that the current top-level examples folder is managed by the schema tooling, so would be inappropriate. I recommend we create
docs/hsds/examples/
as a folder for non-normative or documentation-specific examples, and then create sub-folders for each topic. This approach is seen elsewhere such as in Open Contracting.