Removing the SDK docs server

[Will Bamberg]

Post-1.0, we've been having some conversations about the future of the
SDK documentation infrastructure, and I'd like to share this proposal
with the group.

The current situation
=============

The current documentation system generates documentation from Markdown,
plus some nonstandard syntax for the API reference, using some Python
scripts. The Markdown is shipped with the SDK itself and dynamically
rendered into HTML via a local (Python) web server and WSGI application
launched with 'cfx docs'. Separate to this, for each release we build a
static version of the docs (that is, a set of HTML files that can be
hosted by a Web server rather than rendered dynamically), and upload
them to AMO.

There are a few problems with this situation, three of which are:

* it depends on Python, and we'd like the SDK to be usable without
requiring users to install Python

* there are some usability problems: for example, if the browser does
not ping the local server for a little while (a minute or so) the server
stops running, so if you navigate away from http://127.0.0.1:8888/ and
then return to it, the server may have stopped running.

* it's more complex than it needs to be

Proposal
=====

I'd prefer to remove the docs server, and for the primary version of the
docs to be the static version hosted on AMO.

We would need to keep 'cfx sdocs' so we could build the static doc set,
but 'cfx sdocs' is a lot simpler than 'cfx docs', and this would mean
you only need Python if you have to generate a doc set, which most users
of the SDK don't have to do.

One disadvantage would be for people writing SDK documentation: at the
moment 'cfx docs' gives a nice quick feedback loop for people making
changes to the docs. So to replace this we might enable 'cfx sdocs' to
launch the browser and load the local HTML it just built, and also
enable it to generate only a single file, so as to make this process
faster ('cfx sdocs' takes a few seconds to process all the files).

So the proposal would be:

* change 'cfx docs' so it launches the browser initialized with the
static version of the docs on AMO. This would not need to depend on
Python (it would in this version, but would be trivial to remove that
when we get around to removing the Python dependency from the rest of
cfx). Thus, to people not editing the docs, the behaviour would be
pretty similar.

* keep 'cfx sdocs' as it is, but add two new options:

'--run' to generate the static doc set locally, but rather than
compress them, run Firefox initialized with the index file for the newly
generated doc set

'--filename=<file>' to generate the HTML for the single specified
file, then run Firefox initialized with that file

Some Remaining Problems
================

Some problems not addressed in this proposal:

* 'cfx docs' would not work offline

* a user of the SDK who's getting the latest builds from GitHub would
not get the most up to date documentation, unless they were also
prepared to run 'cfx sdocs'.

If you have any comments on this proposal, as a user of the SDK, an SDK
developer, or both, I'd love to hear them.

Will

[Erik Vold]

One piece of the puzzle I'm not seeing mentioned here is that third party module developers are also writing docs, and the only place where those docs can be viewed atm is via the sdk documentation infrastructure.

So if a developer wants to read https://github.com/erikvold/toolbarbutton-jplib/blob/master/docs/toolbarbutton.md the only place they can do so atm is by adding the package to their sdk and viewing the docs in cfx docs.  There doesn't appear to me to be any place in the builder where a module developer can but their docs either..

My 2c fwiw is that this plan needs to describe how a third party module developer is supposed to publish their docs for consumers.

Erik

--
You received this message because you are subscribed to the Google Groups "mozilla-labs-jetpack" group.
To post to this group, send email to mozilla-labs-jetpack@googlegroups.com.
To unsubscribe from this group, send email to mozilla-labs-jetpack+unsub...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/mozilla-labs-jetpack?hl=en.

--
Erik Vergobbi Vold

Email: erik...@gmail.com
Website: http://erikvold.com/

Github: http://github.com/erikvold
Identi.ca: http://identi.ca/erikvold
LinkedIn: http://www.linkedin.com/in/erikvold

[Nick Fitzgerald]

FWIW, as the developer of a very small jetpack addon, I have found the
docs server to be very helpful. It allows me to side step worrying about
what version of the sdk I am using and which docs correspond to that
version, and instead I just see the docs that I *know* are correct for
the version I am using.

Cheers,

Nick

[Nick Fitzgerald]

Sorry just re-read the proposal more closely. I think as long as the
most recent docs are available, it doesn't matter so much *how* they are
provided.

Cheers,

Nick

[Jeff Griffiths]

On Fri, Jul 15, 2011 at 8:27 PM, Nick Fitzgerald
<nfitz...@mozilla.com> wrote:

> Sorry just re-read the proposal more closely. I think as long as the most
> recent docs are available, it doesn't matter so much *how* they are
> provided.

The only counter-argument I can think of is: what if I'm on a plane?
Or other places without net access. It *would* be cool to be able to
generate static docs locally, or alternatively check out a git repo
containing the docs with tags for various releases of them.

$.02, Jeff

[Hernan Rodriguez Colmeiro]

I think the most concerning thing is what Erik raised, 3rd party
documentation will be hard to integrate. That is something that should
be considered.

Hernán

[Drew Willcoxon]

It's not 100% clear, but I don't think Will is suggesting that
third-party docs would go away. There's no reason 'cfx sdocs' couldn't
work for all packages, third-party or otherwise.

I understand the purpose of redirecting to AMO via 'cfx docs' -- one
less Python dependency, which is great -- but that solution bothers me,
since it's an SDK-specific hack that's not generalizable to all packages.

I think a better solution would be to allow packages to optionally
include pre-built docs. 'cfx docs' would then traverse the packages
inside of cfx's working directory, launching the browser with any
pre-built docs it finds. If there are no pre-built docs but there are
the raw Markdown files, then it would delegate to 'cfx sdocs', generate
the docs, and then launch them in the browser -- failing if Python, or
whatever doc generating platform we use in the future, is unavailable.
(I hope cfx eventually lives in the browser, and in that case docs could
be generated there.) That would mean some re-organization of the SDK's
docs, out from the static-files directory and into addon-kit and
api-utils, but I think such a re-organization makes sense anyway.
"High-level" docs go with the "high-level" APIs in addon-kit; low-level
with api-utils. Plus, the SDK would be using the same doc-related
tooling and conventions that third-party devs would use, which is good
for the entire ecosystem. It would add another step to the SDK's
release process, but that seems like a small price.

How about that?

Drew

[Erik Vold]

Could cfx docs run cfx sdocs and open the index.html page?

Erik

--
You received this message because you are subscribed to the Google Groups "mozilla-labs-jetpack" group.
To post to this group, send email to mozilla-labs-jetpack@googlegroups.com.
To unsubscribe from this group, send email to mozilla-labs-jetpack+unsub...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/mozilla-labs-jetpack?hl=en.

[Will Bamberg]

Hey

Thanks for the feedback, it's very helpful.

I hadn't properly considered 3rd party modules, which I'd agree more or less sinks this suggestion for the time being. Nick's point that cfx docs guarantees that the docs match the code is also a good one.

On 11-07-15 11:01 PM, Erik Vold wrote:

Could cfx docs run cfx sdocs and open the index.html page?

Yes, but sdocs is slow, so it would be better to do that only for source files that don't have corresponding built docs (i.e. the first time it runs, or the first time after a new package is dropped into the tree) and _maybe_ any time after the source docs had been modified (although it might be OK to require that this use cfx sdocs).

This would remove the docs server, so fixes the usability problems associated with that. It doesn't remove the Python dependency, but does simplify the code to the extent that implementing it in the browser would be easier.

So that's what I'll look at, for the first pass.

Drew:

 That would mean some re-organization of the SDK's docs, out from the static-files directory and into addon-kit and api-utils, but I think such a re-organization makes sense anyway. "High-level" docs go with the "high-level" APIs in addon-kit; low-level with api-utils.

I don't understand why this is necessary for this proposal. Something like it would be needed to enable packages to add tutorials and guides into the SDK, rather than just API docs, and that would be a good thing, but that sounds like a different bug to me.

Will

Erik

To post to this group, send email to mozilla-la...@googlegroups.com.
To unsubscribe from this group, send email to mozilla-labs-jet...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/mozilla-labs-jetpack?hl=en.

--
Erik Vergobbi Vold

Email: erik...@gmail.com
Website: http://erikvold.com/

Github: http://github.com/erikvold
Identi.ca: http://identi.ca/erikvold
LinkedIn: http://www.linkedin.com/in/erikvold

--
You received this message because you are subscribed to the Google Groups "mozilla-labs-jetpack" group.

To post to this group, send email to mozilla-la...@googlegroups.com.
To unsubscribe from this group, send email to mozilla-labs-jet...@googlegroups.com.

[Drew Willcoxon]

> Drew:
>> That would mean some re-organization of the SDK's docs, out from the
>> static-files directory and into addon-kit and api-utils, but I think
>> such a re-organization makes sense anyway. "High-level" docs go with
>> the "high-level" APIs in addon-kit; low-level with api-utils.
> I don't understand why this is necessary for this proposal. Something
> like it would be needed to enable packages to add tutorials and guides
> into the SDK, rather than just API docs, and that would be a good thing,
> but that sounds like a different bug to me.

I was responding to the implication of your proposal that third-party
docs would go away. (And I don't see, BTW, why we would need to shut
out third-party docs in order to remove the doc server.) I started with
the basic idea of supporting pre-built docs as an alternative to the
server, and then followed it to one possible conclusion, that's all.

Drew

[Matej Cepl]

Dne 16.7.2011 08:01, Erik Vold napsal(a):

> Could cfx docs run cfx sdocs and open the index.html page?

+1 I believe that there are more people than just myself who are used to
run cfx doc and who wouldn't be happy if it broke when they are offline.
Add cfx doc (or something), but couldn't cfx doc be made into cfx sdoc
(possibly Makefileish ... i.e., regenerate only new pages) which would
in the end show the statically generated result?

Matěj

[Will Bamberg]

Yes, something like that. It would be much slower than the current cfx
docs, though, the first time it ran (several seconds, at the moment,
though maybe that could be improved). But after that it would be pretty
quick.

Will