Display schema extracts and examples

[practicalparticipation]

This issue describes the desired behaviors for including extracts, and sets out options for achieving this. Depending on developing time available, option (2) in each case is preferred, but option (1) is an acceptable fallback for the current iteration if implementation of (2) goes out of scope in the current sprints.

Overall goals

At points during the documentation it would be useful to display for users:

(a) Embedded sub-sections of the schema (achieved using docson)

(b) A table of the schema fields in flattened form (manually generated for now)

(c) An example of this sub-section of data in JSON format

(d) An example of this sub-section of data in CSV format

Each point where this is required may have one or more of (a - d), but may not necessarily have all of these.

Presentation

The ideal presentation of these would be in a tabbed panel - along the lines in the Popolo spec. Bootstrap provides a plugin for this and we could either:

(1) Use the Bootstrap Markup in our Markdown to describe the tabs and panels (simple technology option; less flexible in future if we want to generate print output etc. from docs)

(2) Use some template approach to automatically generate the Bootstrap Markup around tabbed sections.

JSON segments should be pretty printed.

Example mock-ups:

Including examples

Examples could either be:

(1) Written directly into the markdown for the page (easier technical option for rapid implementation, but not good for long term);

or

(2) Included from an external file (either in an /examples/ folder, or in the same documentation folder.)

Using imported files from an /examples/ folder would have the advantage of then being able to potentially validate examples against the schema, and to offer them for easy download.

[ghost]

I just had a check-in with @foobacca and he demonstrated syntax coloured json and csv converted to tables. He explained that the you are already able to do the schema examples using the docson widget.js. But we don't know what kind of content you have in mind for the "field list" tab.

[practicalparticipation]

Thanks. I had in mind a flattened list of the definitions of fields in the format:

Field ID	Field Name	Type	Description
tender.id	Tender ID	string	An identifier for the tender
tender.title	Tender Title	String	A title for the tender

Thinking at present this could be manually generated as a CSV file and handled the same way as CSV, or I have been looking at whether this could be generated by a markdown plugin - but that would be something I would need to create / something for future iteration.

[foobacca]

btw - I've been documenting the conversion process in this file: https://github.com/open-contracting/standard-collaborator/blob/multifile/django/website/README_CONVERSION.md

This includes how I'm including json and csv files - let me know if that will meet your requirements.

[practicalparticipation]

This looks great: documentation is clear and this makes good sense.

[foobacca]

I'm afraid I've run short of time to do anything nice for tabs, but here's an example of json and csv in tabs in markdown: https://raw.githubusercontent.com/foobacca/standard/master/standard/docs/en/01_standard/01_intro.md

[practicalparticipation]

That's ok. I've just pushed these examples to my repo, but currently getting 500 error on staging server. Will test again in the morning.