2

I'm working on a Json Schema: https://github.com/andrejellema/GlobalCoffeeDataStandard/blob/master/global-coffee-data-standard.schema.json

I need to document this and am looking at ReadTheDocs. With it, I can manually create .rst-files, but I want it to be closely linked to my schema. Meaning it will generate the .rst files based on the title and description in my schema and generate the appropriate TOC and also insert the relevant JSON code. Later I can manually alter the .rst files and add more descriptive content.

The goal is to let non-developers manage the documentation.

Is that even possible? Or perhaps with a different documenting tool?

Paul Meems
  • 3,002
  • 4
  • 35
  • 66
  • Not sure if this is helpful, but have you looked at [JSON-LD](https://en.wikipedia.org/wiki/JSON-LD)? Or [RDF](https://www.w3.org/2001/sw/wiki/RDF) in general? – user Feb 01 '19 at 19:15
  • It's not *entirely* clear for me what your goal is. But you might want to have a look at https://github.com/AnalyticalGraphicsInc/wetzel . (An unrelated side note: I doubt that it makes sense to put *absolute* URLs into the `$ref` of a schema. These should usually be just a file name (of a schema file in the same directory)). – Marco13 Feb 01 '19 at 19:17
  • Thanks for the links. `AnalyticalGraphicsInc/wetzel` seems interesting. I'll give it a try. And also thanks for your side note. I'll change my absolute ref links to relative ones. – Paul Meems Feb 02 '19 at 15:45
  • An aside: When replying to a comment, you can use @Marco13 to mention people and let them have a notification about your response. (I only stumbled over your response now accidentally) – Marco13 Feb 08 '19 at 16:47
  • We decided to continue with ReadTheDocs. And I created my own parser so my rst files are generated from my JSON Schema, keeping my docs in sync with my schema. Thanks @Marco13 and user for your input. – Paul Meems Feb 09 '19 at 18:23
  • @PaulMeems Have you published your parser for json schema to RST? That would be extremely useful to me – Brendan Samek Apr 11 '19 at 05:06
  • @BrendanSamek You can get it here: https://github.com/globalcoffeeplatform/CoffeeDataStandard/tree/master/generator It is customized for our needs and you can start the process by running a unit test. No documentation available except for some inline comments. – Paul Meems Apr 12 '19 at 06:49

0 Answers0