551042 - Figure out how to release Jetpack 0.2 SDK documentation

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: General, defect, P2)

Description

[Atul Varma [:atul]]

As mentioned in bug 548165, we want to have per-version Jetpack SDK documentation online. Right now the version 0.1 docs online at https://jetpack.mozillalabs.com/sdk/0.1/docs/ can't have anything live "alongside" other versions of the docs in the same Python process because the versions of cuddlefish and other modules may be different. We may need to make a build target for cfx that outputs static files for documentation to use, possibly including .htaccess files, to relieve us of having to support WSGI apps with weird configurations (this shouldn't be too hard since the doc server WSGI app is mostly just serving static content).

We should also update the SDK release documentation to tell release folks how to push new docs: https://wiki.mozilla.org/Labs/Jetpack/Release

Comment 1

[Brian Warner [:warner :bwarner]]

I'm working on changes to "cfx docs".. I can look into adding a new command (maybe "cfx generate-docs" ? emit-docs? write-docs?) that emits a static tree of HTML.

Comment 2

[Atul Varma [:atul]]

Oh, I thought I was working on this one... Static HTML would be nice, though one disadvantage of that right now is that the docs are (intentionally) a dynamic JavaScript web-app that talks to a ReSTful server API, so a lot of logic actually occurs client-side.

To do things 'statically' I was originally planning on outputting files that could effectively "stub out" the server API by returning static JSON objects, e.g. flat files on disk. It would certainly not be terribly efficient, but I was assuming that this won't have a tremendous amount of load.

Comment 3

[Brian Warner [:warner :bwarner]]

awesome, go for it. Yeah, I was expecting the static files would include a number of JSON blobs, and users would start with the same main.js that they currently hit, but that the XHRs issued by main.js would be satisfied with the static files instead of strings generated by python code. Most of the python code I've seen so far is just reading bytes off the disk anyways.

I'd think doing it that way would be more efficient than having python serve up those files, since they'll all be static, and apache can use sendfile() on them.

Comment 4

[Atul Varma [:atul]]

Yep, exactly.  Sounds good, I will start busting it up then.

Comment 5

[Atul Varma [:atul]]

Attachment: patch

Comment 6

[Atul Varma [:atul]]

This patch is only partly-implemented, I'm just uploading it as a status update, and to try out my cool new qexportbz HG command (see bug 552370).

Presently, this patch adds a meager test suite to cuddlefish.server, changes the server's '/api/packages/*' path to be '/packages/*', and changes '/api/packages' to be '/packages/index.json', which will make it easy to move to a static file setup.

It also alters the behavior when the wsgi app gets an empty string as a path: we now just return a 404, instead of returning the contents of index.html which then render inappropriately because all the relative paths it references point to nonexistent files (Zandr fixed this on the server-side for 0.1 launch by adding a redirect from '' -> '/').

Comment 7

[Atul Varma [:atul]]

Attachment: patch 2

Comment 8

[Atul Varma [:atul]]

Pushed this patch: 

  http://hg.mozilla.org/labs/jetpack-sdk/rev/c24e09f9e486

Running 'cfx sdocs' now generates a file called 'jetpack-sdk-docs.tgz' which contains 100% static files that can be served from a file: URL or a standard web server.

Comment 9

[Zandr Milewski [:zandr]]

So the remaining deployment question is:

Should 'latest' 301 to the latest version, or should it be a symlink? That is, should the address bar continue to show 'latest' as you browse the latest docs, or should the user be redirected to whatever is the latest at the time?

Comment 10

[Atul Varma [:atul]]

Personally, I think it should probably be a redirect, since we'd prefer for links to specific pages on the latest docs, when dropped in e.g. forum posts, to not cause weird anachronisms whereby someone discussing function foo() points to a link at 'latest' that no longer exists at the time of reading. If that makes sense.

OTOH, there is a usefulness for a separate 'trunk' symlink, which we should consider moving the WSGI app to point to: this way, a cron job on the server can just hg pull the latest repo and the 'trunk' docs represent the SDK docs of the trunk.

Comment 11

[Zandr Milewski [:zandr]]

'latest' should 301 to the current tagged release.
'trunk' should be the wsgi app running against a checkout that is kept current either by cron or a commit hook (likely the former)

Roger Wilco

Comment 12

[Zandr Milewski [:zandr]]

latest is redirecting to 0.2 as of now.

'trunk' is blocked on getting a jetpack-sdk-docs.tgz for 0.1

Comment 13

[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".