Using Sphinx to document configuration files in e.g. JSON, YAML, etc?

[Ramon]

Hi all --

We are defining an integration SDK that includes some fairly involved parameter files, currently formatted in YAML syntax. I’d like to provide “sample code” for these configurations (i.e. sample configuration files) as well as detailed technical documentation on the format requirements (data type constraints, etc). We are not wed to the YAML format yet, so if another roughly equivalent format (e.g. JSON) is well-supported in Sphinx we’d consider switching as getting the documentation in good shape to encourage adoption by developers is a key goal.

Are there any Sphinx approaches for documenting data structures or parameter / configuration files like this? 

Thanks in advance!

Ramon

[Guenter Milde]

The PyLit bidirectional text/code converter can be used for "literate config
files" in any config file syntax with documentation in reStructuredText.
Pylit will convert the file from rst with code snippets to code with
extensive comments and back. For an example config file, see
http://pylit.berlios.de/conf.py.html

Günter

[Viktor Haag]

On Thursday, 17 May 2012 18:19:17 UTC-4, Ramon wrote:

Are there any Sphinx approaches for documenting data structures or parameter / configuration files like this? 

It's not YAML, it's JSON, but for our project where we're documenting a RESTful API, we use a locally extended version of the default JSON lexer in Pygments to document the JSON data structures that pass back and forth through our API. 

The extension to the JSON lexer is done to add support for in-line commenting in the JSON blocks that appear in our docs: I simply added these two regular expressions to the group of "whitespace" definitions:

            (r'//.*?\n', Comment.Single),

            (r'/\*.*?\*/', Comment.Multiline)

And now I can use c-style or c++ style commenting in our docs' JSON blocks and have it parse properly and get prettified in the output.

In the ref docs themselves, I use constructions like this to document the structures and pin them into the indices and such:

.. comment identifying the service Class that defines the structure

     .. js:attribute:: Package.ClassName

        .. code-block:: json

           {

              "Property": "<string>"  // String property

           }

Note that we use a special convention in our docs (the "<string>") that declares the type of the Property in "legal JSON" that the lexer will handle. If you want a more fulsome description of the conventions we use, you can look at our project's "conventions" topic (http://docs.valence.desire2learn.com/basic/conventions.html) and the surrounding docs for examples.

--

Viktor

[Ramon]

Hi Viktor --

Thank you for the detailed write up -- this sounds very close to what we are looking for. I take it you were able to extend the existing JSON support for this, so we'd need to presumeably implement a YAML parser to take a similar approach. Do you happen to know if anyone is working on something like this?

Ramon

[Viktor Haag]

On Friday, 25 May 2012 13:49:44 UTC-4, Ramon wrote:

Hi Viktor --

Thank you for the detailed write up -- this sounds very close to what we are looking for. I take it you were able to extend the existing JSON support for this, so we'd need to presumeably implement a YAML parser to take a similar approach. Do you happen to know if anyone is working on something like this?

According to the pygments website, the latest distribution supports YAML (http://pygments.org/languages/) and has since Pygments 0.11. Accordingly, you could use 

.. code-block:: yaml

to introduce YAML blocks. The lexer for YAML is in the "text.py" source-file of lexers in the Pygments distribution. A quick glance at it seems to indicate that it contains support for noticing in-line comments and rendering them as such. You might not need to hack the lexer at all to get the look that you want.

--

Viktor