555180 - integrate into "cfx docs" an "apidoc/annotated sources" module view based on "code illuminated"

Status: RESOLVED FIXED

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

Description

[Luca Greco [:rpl] [:luca] [:lgreco]]

User-Agent:       Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.2) Gecko/20100115 Firefox/3.6
Build Identifier: 

This prototype use the existent server side python api and is modeled after the module markdown content generation.

I'm using the existent markdownToHtml instead of the creole parser used in the
original code illuminated, the content is generated browser side as in the current module view, and it's presented as a different module documentation view.


Reproducible: Always

Comment 1

[Luca Greco [:rpl] [:luca] [:lgreco]]

Attachment: jetpack-sdk/code-illuminated integration prototype

Comment 2

[Luca Greco [:rpl] [:luca] [:lgreco]]

I'm pretty sure this patch needs some further work on css styles and some small code cleanup (currently I've not integrated code-illuminated css styles because of possible conflicts with current "cfx docs" stylesheets)

Comment 3

[Atul Varma [:atul]]

Thanks Luca, this looks great!

A few comments:

* I think it might look better if the "Overview | API Doc" line were below the header, so that the header lined up with the "Jetpack SDK Docs" header on the left column. It would be nice if the first line of the sources/docs was also aligned with the baseline of the "Developer Guide" line on the left column.

* For Jetpack packages, we're actually thinking that the markdown documentation will contain the public API documentation as well as any necessary overview information, while the source code mostly contains implementation notes--kind of like how Python's documentation+source is structured. In this vein, maybe "Overview" should be called "Documentation" and "API Docs" should be called "Source Code" or "Annotated Source Code"?

* It would be super cool if the particular section someone was in -- Documentation or Source Code -- was highlighted in the "Documentation | Source Code" selection, so the user knew which one they were currently viewing.

What do you think?

Comment 4

[Luca Greco [:rpl] [:luca] [:lgreco]]

Attachment: jetpack-sdk/code-illuminated style tweaks and annotated sources generation bugfix

Comment 5

[Luca Greco [:rpl] [:luca] [:lgreco]]

sounds good ;-)

I've attached a patch of the patch ;-)

all styles tweaks applied and bugfixed sourceToApidoc.

It make sense to rename "apidoc" to "annotated_source" into main.js too, isn't it?

Comment 6

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

Assigning this to Luca, who seems to be actively working on it.  Luca: please correct me if that's wrong!

Comment 7

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

Comment on attachment 436331 [details] [diff] [review]
jetpack-sdk/code-illuminated style tweaks and annotated sources generation bugfix

Requesting review from Atul on this second patch to make sure it gets on his radar.

Comment 8

[Luca Greco [:rpl] [:luca] [:lgreco]]

(In reply to comment #6)
> Assigning this to Luca, who seems to be actively working on it.  Luca: please
> correct me if that's wrong!

Sure, I'm actively monitor this ticket and I can do a rebase of the patches on my git mirror anytime, if necessary.

Comment 9

[Luca Greco [:rpl] [:luca] [:lgreco]]

Attachment: Updated annotated sources based on code-illuminated (based on 556:db9af05cd6b1)

I've just rebased and tweaked "module annotated source" patches on the new tip, but I'm not so sure of some points:

* syntax for module "source annotations" and apidoc are different (and I'm not sure developers will be happy of that)
* source annotations and apidoc have different meanings but we (developers) need a good reason to use both methods/syntaxes

If we decide that we don't want two different annotation/apidoc syntax or that the two feature are not sufficiently different, I can rewrite it as a simple "syntax highlighted" view of the module sourcecode.

P.S. if we decide to complete this feature I need to add some documentation, to explain how it works.

Comment 10

[Atul Varma [:atul]]

Awesome, thanks Luca! Sorry I haven't looked at this yet--I will soon.

Good point about the different methods/syntaxes here.  Hmm.  Another thing I've noticed is that some LLJAPI developers are duplicating their docs, putting them both in the Markdown documentation and in the code, which I thought the jsdoc-like doc parser (see bug 549786) was supposed to circumvent.

Sounds like we may need to discuss this a bit more on the Jetpack google group.

Comment 11

[Atul Varma [:atul]]

Oh! I just found bug 560656, "Come up with some documentation conventions". I'm gonna go ahead and say that it's blocking this bug.

Comment 12

[Drew Willcoxon :adw]

(In reply to comment #10)
> Good point about the different methods/syntaxes here.  Hmm.  Another thing I've
> noticed is that some LLJAPI developers are duplicating their docs, putting them
> both in the Markdown documentation and in the code, which I thought the
> jsdoc-like doc parser (see bug 549786) was supposed to circumvent.
> 
> Sounds like we may need to discuss this a bit more on the Jetpack google group.

bug 560656

http://groups.google.com/group/mozilla-labs-jetpack/browse_thread/thread/a9fd21bd1009ee1a

Comment 13

[Luca Greco [:rpl] [:luca] [:lgreco]]

Some days ago I started to better analyze the problem and now I've a better idea of the problem and possible solutions:

The main problem is that  jetpack need a proper apidoc, by now every module
needs a separate markdown file and every change in the source needs a context swap to be documented.

It could be simpler and more natural if we could add apidoc comments into the sourcecode (as dietrich suggested some days ago on irc), so I've done a small change into server.py, apiparser.py and main.js to render the current jetpack <api> syntax embedded into the source files.

With some small changes we could use markdown to write developer manuals and tutorials embedded into the jetpack module, and write apidoc comments embedded into the sourcecode as we are used to.

Comment 14

[Luca Greco [:rpl] [:luca] [:lgreco]]

Attachment: prototype of parsing/rendering apidoc embedded into sourcecode

Comment 15

[Atul Varma [:atul]]

Thanks Luca!

Hmm, so when I apply your patch and go to any of the module documentation pages in jetpack-core, I just get a page with "Module 'foo'" at the top (where foo is the name of the module), but the rest of the content area is empty. It seems to be doing this both on Firefox 3.6 and Safari... Any suggestions?

Comment 16

[Atul Varma [:atul]]

Ah, nice, so here all the per-module docs are generated straight from the source... Cool.

How would you propose doing things like introductions, tutorials, and so forth? Should those just be contained in specially-formatted comments, or kept in the Markdown files in the docs/ subdirectory?

Comment 17

[Luca Greco [:rpl] [:luca] [:lgreco]]

I've tried to extend package details to a package documentation browser:

https://bugzilla.mozilla.org/attachment.cgi?id=444256&action=diff#a/static-files/js/main.js_sec4

It's just prototyped, so it need some work to better integrate a doc page
navigation section into the package detail view.

Comment 18

[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 19

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

We integrated code highlighting into the documentation a few months ago, so I think this is actually fixed (albeit via a different route).  Please correct me if I'm wrong, however!