564825 - apiparser - documentation for markdown files

Status: RESOLVED WONTFIX

(Add-on SDK Graveyard :: General, enhancement)

Description

[Piotr Zalewa [:zalun]]

User-Agent:       Mozilla/5.0 (X11; U; Linux i686; en-US) AppleWebKit/533.2 (KHTML, like Gecko) Chrome/5.0.342.9 Safari/533.2
Build Identifier: apiparser.py

I'm using the cuddlefish/apiparser.py to export docs/*.md files
One of the markdown files gives following tuples:

[('markdown', 'description of the module (shortened for example)'),
 ('api-json', {'description': 'description of the property','line_number': 5, 'name': 'id', 'type': 'property'}),
 ('markdown', '\n\n<span class="aside">\nThe [Package Specification](#guide/package-spec) section explains the\n`package.json` file.\n</span>\n\n'),
 ('api-json', {'description': "description of the property",'line_number': 21, 'name': 'data', 'type': 'property'}),
 ('markdown', '\n\n'),
 ('api-json', {'description': 'description of the method', 
'line_number': 29, 'name': 'data.load',
                 'params': [{'description': "description of the param",
'line_number': 35, 'name': 'name', 'required': True, 'type': 'string'}],
                 'returns': {'description': '', 'line_number': 38,
'type': 'string'},
                 'type': 'method'}),
 ('markdown', '\n\n<span class="aside">\nThe 0.4pre SDK release does not have the Panel API yet. Watch \n[JEP 103](https://wiki.mozilla.org/Labs/Jetpack/Reboot/JEP/103) for
updates.\n</span>\n\n'),
 ('api-json',{'description': 'method description', 'line_number': 46, 'name': 'data.url',
                'params': [{'description': "param description", 'line_number': 55, 'name': 'name', 'required': True, 'type': 'string'}],
                'returns': {'description': '', 'line_number': 58, 'type': 'URL'}, 'type': 'method'}),
 ('markdown', '\n')]

I've got no idea how to treat the 'markdown' tuples. Are these always between api-json tuples? Is there any doc explaining these? 

I'm looking for something like
 * first "markdown tuple" is about a Module
 * second is the package.json explanation
 * third ...

etc.


Reproducible: Always

Steps to Reproduce:
1. text = open(doc_file)).read()
2. pprint(list(apiparser.parse_hunks(text)))

Comment 1

[Brian Warner [:warner :bwarner]]

As far as I know, we don't yet have any conventions for this: it would imply a stronger format spec on the .md files than we have so far.

In general, I expect documentation authors to start their .md files with some prose about what the module does and why it is useful. Then they'll probably show some sample usage (with lots of <code> blocks). Eventually they'll need to give a more structured explanation of each available API object and methods. These structured explanations will appear as "api-json" chunks.

As far as the API parser is concerned, the .md file is made up of a series of chunks, each of which has a type, and it just turns the whole thing into a list of these chunks. We might add more recognized types in the future, so tools should ignore any chunk-type that they don't understand, and make minimal assumptions about the meaning of unknown types.

A tool which wants to scan for API definitions and render just those should skip all non "api-json" chunks.

I don't know if that answers your question :). BTW, what was the .md file that produced this output?

Comment 2

[Piotr Zalewa [:zalun]]

I think it was self.md 

The starting prose appears as first "markdown" chunk.
Other "markdown" chunks are generated from <span class='aside'>.

Comment 3

[Myk Melez [:myk] [@mykmelez]]

The Add-on SDK is no longer a Mozilla Labs experiment and has become a big enough project to warrant its own Bugzilla product, so the "Add-on SDK" product has been created for it, and I am moving its bugs to that product.

To filter bugmail related to this change, filter on the word "looptid".

Comment 4

[Myk Melez [:myk] [@mykmelez]]

Will thinks Piotr doesn't care about this anymore because the Builder now gets docs in HTML format, but please reopen if that's incorrect!