openreferral / specification

The Human Services Data Specification - a data exchange format developed by the Open Referral Initiative
https://openreferral.org
Other
117 stars 49 forks source link

Manage worked examples using separate files rather than hard-code into docs pages #441

Closed mrshll1001 closed 10 months ago

mrshll1001 commented 1 year ago

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.

### 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:

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.

mrshll1001 commented 10 months ago

This was fixed by #447

Examples are now stored in /docs/figures, and rendered using the appropriate sphinx commands.