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/-/JdQ-q__aNQ4J.
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.
