655401 - Make examples browsable in SDK docs

Status: RESOLVED WONTFIX

(Add-on SDK Graveyard :: Documentation, defect, P1)

Description

[Will Bamberg [:wbamberg]]

Attachment: Auto-generate examples page

Currently the SDK's examples don't integrate very well with the docs. Here's a patch that will build an 'Examples' page from any example add-ons that (1)exist under /examples and (2)contain README.md.

The page just lists the examples, with the README.md and a file listing.

The code is also at: https://github.com/wbamberg/jetpack-sdk/tree/examples

If you think this is a good plan, it would be good to include more examples before 1.0. Because examples are relatively expensive to write I'd suggest trawling through the SDK docs and extracting existing examples.

Possibly we ought also to link to a Wiki page containing examples contributed by the wider community. That would be easy to add into this of course.

Comment 1

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

Comment on attachment 530764 [details] [diff] [review]
Auto-generate examples page

Overall, a useful addition to the docs.  A few issues I noticed while trying it out:

1. Image entries return a page that complains the image cannot be displayed because of errors.  For example, I clicked on annotator's pencil-on.png entry, which directed me to <http://127.0.0.1:8888/examples/annotator/data/widget/pencil-on.png>, which displayed: "The image “http://127.0.0.1:8888/examples/annotator/data/widget/pencil-on.png” cannot be displayed because it contains errors."  Loading the image directly from the filesystem, however, works fine.

2. HTML entries return a page that renders as HTML.  That's not particularly useful, since the HTML doesn't render in a way that is instructive (specifically, when looking at annotation.html, annotation-editor.html, and annotation-list.html).  It would be better for the HTML to render as text so that developers can directly examine the code and copy it into their own addons.

3. When scanning the page quickly, it's hard to discern where one example ends and the next begins.  It would be easier if the titles were outside the blue boxes that contain the examples, or there were thick horizontal rules between them, or some other mechanism was used to differentiate examples.

4. When I first accessed the page, I thought there must be a bug that prevented the reading-data example from showing up.  Later, reading the code, I realized that it's because that example doesn't have a README.md file.  I suppose some developers will never access the examples/ directory from the command-line, and others will never access the docs, but for those who look at both, it'll be strange for the directory to contain an example that doesn't show up in the docs.  I think it'd be better to show all examples, either by not requiring a README.md file or by giving one to reading-data.

Comment 2

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

(automatic reprioritization of 1.0 bugs)

Comment 3

[Will Bamberg [:wbamberg]]

Although there's a patch for this, it's not that useful unless there are more than two examples, and I'm now thinking that having inline, executable examples is a better way to bridge the examples and the docs, so I'd prefer to revive that once the new loader is ready.