I would like to generate useful documentation for a REST API written in Python.
I imagine it should be something like this:
This method creates kittens in the browser
format(default=json): The format in which kittens will be generated.
count(default=10): The number of kittens to generate.
A list of kittens.
My syntax is obviously:
program = dict
dict = repeated(name:string | name:dict)
I would like to parse this format and get (for example) a Python dict, preferably without using regex.
Is there a parser for such a syntax already available?
If not, then what is the simplest way of defining and parsing DSLs in Python?
Note that I would prefer not to use reStructuredText or any format different from what I described.
I'm not sure I understand exactly what you want, but reStructuredText can be used to capture the information in your example:
.. method:: kittens(format="json", count=10) Creates kittens in the browser. :param format: The format in which kittens will be generated. :param count: The number of kittens to generate. :return: A list of kittens
Sphinx understands this syntax, which is an extension of the basic reST markup defined by Docutils.
Its a online documentation tool. Its awesome and it will do exactly what you want.