Target format/structure for intermediate representation of documentation

[uliska]

Whenever documentation is generated it should first produce an intermediate representation in a to-be-discussed format. The steps to this involve (and more?):

• Parsing the VBCL file(s) (see also Specification for package/module file documentation #19)
• Parsing LilyPond and Scheme files (Specification for Scheme/LilyPond function documentation #20)
• Reading/converting Markdown files
• Compiling and "linking" LilyPond snippets

This intermediate state should be organized in a way that it can as effortless be used by all targets specified in #21, including live apps that just want to read data and site builders that generate HTML (or other) documentation.

Blocks #26

[Cecca]

As for the data representation to be used, I think that JSON might be our best bet, since there are parsers available for the majority of languages, and may come with a built-in one. In any case, there are so many options available that it might be worth to look at the alternatives.

An orthogonal issue is what we should put into this intermediat representation. Some suggestions:

• Version of the intermediate representation
• list of documentation elements, consisting of
  • element name
  • element type
  • documentation string
  • source file
  • line number

[uliska]

I also tend to think that JSON is a good choice, but don't want to settle on it earlier than necessary, i.e. before having considered the alternatives.

The intermediate representation could also be based on Markdown or a similar format, something that static site (or documentation) builders use as source material. The first step of gathering the documentation from the package files could also produce a directory that can directly be processed by a tool like Sphinx, Pandoc or Gitbook.

The question of a list of documentation elements is directly related to the question of the documentation structure (#19)