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
On Tuesday, May 22, 2012 7:25:50 AM UTC-7, Viktor Haag wrote:
>
> 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
>
>
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To view this discussion on the web visit
https://groups.google.com/d/msg/sphinx-dev/-/das2cTGUkU4J.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
