API Documentation about chaplin

[paulmillr]

yep. https://github.com/moviepilot/chaplin/tree/development/coffee/chaplin.

except of this and readme, there are no docs.

[molily]

At the moment, there’s no dedicated class/method reference, but this is planned for the next release.

[paulmillr]

We should probably use http://readthedocs.org because it's awesome and is very simple (all we need is to create a docs directory with some files).

[karellm]

I've actually started to look around Github Pages and Jekyll to right a beautiful documentation.

I'm thinking of using Jekyll Bootstrap: http://jekyllbootstrap.com/

What do you think?

[paulmillr]

their site looks like shit in safari. so, meh, not cross-browser.

Read the docs is a perfect solution for docs.

• it generates great TOC http://readthedocs.org/docs/andrew-schoen-pycon-2012-notes/en/latest/
• it has SEARCH (!! the most important part)
• it supports documenting of different versions (0.9, 1.0 etc)

[karellm]

Huh? We are using jekyll, not their website. If they don't know how to do a website doesn't make the technology wrong. Plus bootstrap is independent from jekyll and just provide a starting point. If it can reassure you, Jekyll is supported by Github for pages.

I looked at RTD and it is typically the documentation I hate. Not accessible, not readable... and ugly.

Search isn't a big deal. It makes sense when you need to look into a huge API doc (like rails or ruby let say). For a small project like chaplin, nothing is better than the backbone style documentation. One single page, everything at one click. If you want to search, we can use the native browser search.

And I know it isn't optimal but we can create one page per version.

[paulmillr]

I know, I run my personal site on jekyll. It's ok, but not for docs.

rtd is pretty readable, official python documentation is made in this way. And it's the best documentation in the world.

http://docs.python.org/library/index.html

Seems that we'll need @molily opinion on this.

[karellm]

I looked at the python doc and it convinced me not to use rtd. I guess it really is a matter of taste ;)

@molily ?

[damassi]

Regardless of the functionality, RTD, imo, is horrendously unreadable and sloppy, particularly for newcomers. Since documentation is, generally, the largest barrier of entry into a new technology, it's important to keep it simple, well-designed and user-friendly.

[molily]

I have to admit I don’t have a clue about the services presented here. For the start I personally don’t need any fancy helper, since the most work will be to write good text. With paragraphs, headings, lists, code examples, links. It’s pretty much that I think. For the start, I’ll write that in Markdown, plain HTML, whatever. For my part, let’s do simple .md files directly a repository, I like to have the docs directly browsable in the repo and it’s nice to have them in place after cloning the repo. Or plain HTML with a simple stylesheet, doesn’t matter to me. Both will work fine for people who want to use Chaplin, I guess.

AFAICS, Chaplin isn’t so big at the moment that we need to formalize the documentation. At the moment, I’d like to write more a tutorial/how-to style documentation than a classical class/function reference. For the latter, probably a system like JsDoc or so could help in the long term, but I have little experience with that.

[karellm]

You can look at the chaplinjs.github.com repo in the chaplin organization. And type the url to see the result. I stopped editing the pages waiting for your decision but I'd be happy to do a quick sample of docs tonight.

BTW, Jekyll is supported by Github pages and allows for any type of text formatting language, including textile, markdown and so on. And the end result is pure HTML automatically generated by Jekyll. That way we can easily style the docs beautifully (I couldn't agree more with @damassi).

[karellm]

I've put a "proof of concept" in place that allows for multiple versions of the doc here: http://chaplinjs.github.com/

The first page is the changelog and you can see a "read the doc" link near each version. Then you get the doc for that version. I also added a version switcher, in case you'd be landing on the wrong doc version.

To edit the docs, just edit the files in the version/ folder of the chaplinjs.github.com repo. If you want to edit version 0.3, just go to version/0/3. For now, it is a simple index.md file. (Maybe it will be a good idea at some point to break it down into parts and let the index merge them to edit the doc more easily)

I've also ported the README as Manifesto (it is more an essay than a doc) and the AUTHOR. We could remove them from the repo and edit the README to point to chaplinjs.github.com.

If you like it, I'll start righting the API docs this weekend. If not, no worries, I wanted to play with these technologies for another project anyway.

[chadhietala]

Just out of curiosity, is the documentation going to cover SEO related issues. I've noticed that moviepilot is a somewhat content heavy site, but it's not using hashbanged URLs. Is there canonical pages sitting behind these pages? I noticed that there is an object called MovieExplorerConfig within the document that is object representation of the content. Maybe this is separate issue?

[karellm]

BTW, @molily what do you think of the github page template? As I haven't heard back from you, I stopped editing it. Should I start writing the API docs?

[molily]

@chadhietala: moviepilot.com is using the HTML5 History API (pushState). With normal URLs, we can render content on the server to make it accessible for search engines, browsers without JS etc. The raw data is included as JSON in the initial HTML for the JS app.
Chaplin itself does not enforce this way, you can also use plain hash URLs, or hashbang URLs for search engine accessibility. Personally I would recommend the pushState approach, but Chaplin as a software is agnostic in this regard.

[molily]

@karellm Haven’t found the time to look into that more deeply, but it looks very promising, so go ahead! Haven’t worked with Jekyll yet, but several colleagues recommended it.

[karellm]

@molily I've been a bit out of the loop regarding Chaplin because of a rush at work. I'll spend some time during the week to start the docs.

[lukateake]

@karelim, @molily, @paulmillr et al.

I've set aside the full week of June 18th to grok the new version of Chaplin. (I've been using the 0.3 release for a non-trivial app since March.) I'll happily write documentation as my thanks to you gentlepeople for creating such a great tool.

Relatedly, is there a date to finalize 0.4? I imagine that possessing excellent documentation is a prerequisite to the release. Please let me know what I can do to help, especially in highlighting differences to the previous version (which is a lot, frankly).

[paulmillr]

Well. It's very stable. The faster we'll release it, the better it would be.

I see no reason it should be 0.4 though. 1.0 is fine, if we'll follow semver, because it's used in production.

[karellm]

@lukateake Thanks a lot for your proposition. I should start the api documentation of the libraries tomorrow. Any help is welcome. I'll have a better picture of the work when started.

If you can write a from v0.3 to v1.0, that'd be awesome too. @paulmillr I agree that the upcoming should be v1.0.0

[chadhietala]

If you guys need help with any of the documentation I'm willing to help out also. Also agree with @paulmillr about versioning.

[molily]

I’ve set up a structure here:
https://github.com/chaplinjs/chaplinjs.github.com/tree/master/jekyll/pages
with some meta pages and pages for the invididual module documentation (Application, Dispatcher, Layout, Controllers…).

I’d start with pulling the README.md apart and copying the text into the individual files, the start to rewrite and extend it further. Feel free to start with any of these parts. I’ll start with an architectural overview, then going on with Getting Started. I’ve also set up a vanilla boilerplate repository we can reference there.

[karellm]

@molily the problem I see is that the documentation won't be versioned like that. Plus I think a one pager documentation is really nice and I don't know if it is easy to merge .md files and make a menu with jekyll.

And also I think you have put the architecture.png in /assets instead of /jekyll/assets. The workflow is a bit weird due to Github limitation for jekyll plugins. We need to compile jekyll code locally in the root:

1. Start jekyll --server inside the /jekyll directory (not the root)
2. Develop in /jekyll. You shouldn't touch any file in /
3. Before deploying to github, run the /build.rb script, it will duplicate the /jekyll/_site to the root /

[molily]

Thanks for the instructions, will dive into that soon.

Re versioning: I don’t think we should care about versioning now. Personally I don’t like versioned documentations, they just introduce confusion about what’s the latest, it pollutes search engines with duplicate content etc.

It doesn’t make much sense to document the old 0.4 API since it wasn’t a reusable library with a stable API after all. There will be a changelog for upgrading, sure, but not an extensive documentation.

And in the future I’d like to have API changes right in the respective module reference. Chaplin isn’t so huge yet that we need a really sophisticated versioned API reference IMHO. I can’t anticipate how many breaking API changes there will be, so for now I’d solve versioning by having one documentation with version indicators (like “Introduced in version X”, “Deprecated since version X”, “Method signature changed in version X” etc).

[karellm]

@molily I do agree that Chaplin is not that complicated and that versioned documentation may be overkill. Especially we don't really have any documentation for past versions so it is quite pointless. We will decide wether or not we use it in the future when the decision make sense. (I'll leave it in there for now even if we don't use it)

Here are some random instructions:

• The /deploy.rb script duplicates files, commits them to git and push to the remote rep. I prefer to warn you in case you didn't look at it before running it.
• I would keep /pages for static pages like changelogs, license and so on. All the meta info kinda.
• I will create a /docs folder were we can put the actual documentation.

Works for you? (you can see what the result look like in the rep)

[karellm]

@paulmillr and @molily can you peer-review the documentation format here: http://chaplinjs.github.com/docs/mediator.html

I haven't necessarily paid too much attention to the quality of the text or my english. My main concern for now is to know if the format work for you.

[paulmillr]

@karellm looks fine to me.

[molily]

That’s great, @karellm. I like the structure. Don’t know if it makes sense to reproduce the whole module code verbatim (fine for smaller modules with good code readability, problematic for big ones with ugly internal code), but we’ll figure out.

[damassi]

Yes, agreed. I think this documentation is fantastic, the way documentation should be done. Can't wait to use Chaplin in my next project.

[karellm]

@molily we have almost finished the API documentation (with the help of @chadhietala). It would be good if you could review the content also.

Regarding the code verbatim, I was thinking of replacing it with a link to the repo already. How do you like that?

[chadhietala]

@karellm I'm working on the SyncMachine documentation right now. Just a heads up so we don't do the work twice.

[molily]

@karellm @chadhietala I tried to check out the latest changes in https://github.com/chaplinjs/chaplinjs.github.com, but I can’t get jekyll --server running any longer. I’m getting tons of Maruku errors, eventually it fails with an exception.

Do I have to use a specific gem or Ruby version?

[karellm]

@molily Here are the steps I follow:

1. cd jekyll
2. jekyll --server
3. I do my edits, and see locally how it renders. Locally, I have a vhost that points to /jekyll/_site
4. Once I'm done, I deploy with ./deploy.rb in the root (remove old files, copy the jekyll/_site folder to /, commits and push the files to github)

The reason for that weird process is that github disable jekyll plugins and the site won't render. We need to precompile it locally and then push it as a static website (that's the reason for the .nojekyll file).

Let me know if you have problems. I'm quite busy those days but I'll try to finish this documentation soon.

[chadhietala]

@molily I follow the steps that @karellm posted.

[chadhietala]

So is there any timeline for when the official 1.0 cut will be made?

[molily]

@chadhietala Despite of the great work so far the documentation isn’t in a release-ready shape. I’ll concentrate on the documentation to bring that forward. That’s the only thing which is missing at the moment for 1.0.

[SamuelTilly]

May i suggest wintersmith for documentation http://jnordberg.github.com/wintersmith/ i think considering that it utilizes node, coffeescript and all kinds of template-engines it would be a nice complement to chaplin.

[paulmillr]

The documentation is now located in docs dir of repository.

The stuff we still need to doc: utils, collection view, "getting started".

[paulmillr]

thanks to @akre54, the issue can be now closed. we have everything documented somehow. little changes & polishing (& getting started guide) are still required, but the skeleton is production-ready.