A proposal for hosted docs #569
Conversation
|
good job in this case. we should add links to all doc files from each file, like most doc systems do. no need to hide this and it will take not much space |
|
Glad you like it. Will put more work into this towards the end of the week. I agree about placing links to all other modules in each doc file, will probably go for a sidebar of sorts. |
|
This looks good so far. @paulmillr @mehcode Some explanation: @knuton worked with me on moviepilot.com in 2011/2012 and he contributed much of the initial code that made it into Chaplin. Now 9elements is sponsoring him to work on Chaplin again. The first steps will be to improve the documentation, examples, articles and marketing since that’s a major weakness – the code quality is quite good and Chaplin has great features, but we need to communicate this better. |
|
Great news to hear docs/marketing are going to get a nice push :)
Please do 👍 I encounter some people who won't consider Chaplin because they "haven't heard of it." - Which is a silly reason not to consider something, but nonetheless it happens. |
Had originally planned on building a widget for inline switching for each separate example, but realised that the common use case will be to switch language once and leave it at that. So there is no need to group the code examples into "same semantics" lists.
I am not entirely happy with the relative links as they are now. Relative links were brittle already with the use of GitHub's section links, where links would break with changing method signatures. This situation has now become even worse, where unrelated changes, e.g. an additional method being added to the docs, can break links. This is because I use RedCarpet's feature of automatically creating heading identifiers and it doesn't use the text of the heading to do so. Maybe going for HTML with IDs here is actually the most reliable choice.
|
Still work in progress, but would be happy about feedback! Current state can be seen here: http://knuton.github.io/chaplin/ Some issues I definitely need to address:
If these changes makes sense to all of you, I would then try to brush up the docs themselves. Thanks for the introduction, @molily! |
|
Nice one! like this. how about making explanations in |
|
In the docs at the moment there is a mix of files with unwrapped text and files with text wrapped at 80 characters. Should any kind of convention be agreed on for this? |
|
I find it easier not to insert line breaks in documentation texts. Inserting or deleting a single word can cause a re-wrap for the next couple of lines. In practice, nobody will correct that so it gets inconsistent. Line-based diffs are fucked up in both cases; Git doesn’t perform a word-diff per default. |
Addresses issue discussed in 0bfa788.
|
Updated version hosted via my fork: http://knuton.github.io/chaplin/ I am now going through the content, trying to simultaneously understand and explain the current code base. |
|
Looks good so far! |
|
Nice work :). EDIT : I think the menu could "stick" |
| class Layout extends Chaplin.Layout | ||
| isExternalLink: (href) -> # some test on the href variable | ||
| ``` | ||
|
|
||
| ```javascript | ||
| // JavaScript | ||
| var Layout = Chaplin.Layout.extend({ | ||
| isExternalLink: function(href) {} # some test on the href variable |
There was a problem hiding this comment.
just saw the typo here (#)
|
ok this needs sync with master. What else is needed to merge this? Can we launch this ASAP? |
|
@Nami-Doc Yes, I have also thought about fixing the sidebar. Any other opinions on this? @paulmillr In principle this is close to being ready for merging, one thing that could be decided first is the above question regarding the sidebar. I am working on the actual content of the documentation at the moment, but this shouldn't necessarily be bound to the technical things that have happened so far. To complete the technical part we should
Then I'd ask you to configure the subdomain appropriately. The more interesting question is about actually getting the docs out of the door. Should anything on chaplinjs.org be updated at the same time? Should this be part of going 1.0? etc. |
Conflicts: docs/chaplin.view.md
|
I think we can release 0.10 with new docs. Fixed sidebar is cool. |
Creates a throw-away repository to which contents of /docs are copied, then force pushes this to the gh-pages branch.
|
If everything looks good, I can squash and we can merge this. (Updated version, as always, at http://knuton.github.io/chaplin/.) Version numbers are handled manually at the moment, right? As I am using the version number to link to the correct versions of source files, there is now yet another place where the version number appears (see this commit). It might be a good idea to add an automatic check of this value in the grunt task for publishing docs and abort if the version number mismatches the one in package.json. How is this handled in general? |
|
Docs look awesome! Great job @knuton. As for versioning we could always add something like https://npmjs.org/package/grunt-bumpx or https://npmjs.org/package/grunt-release. |
|
looks cool. auto-check will be good, yes |
|
@mehcode, yeah, something like this would be great. I think grunt-release looks quite good, but it is too simplistic for our use case, we will want to automatically bump at least |
Conflicts: docs/chaplin.view.md
|
Ready for merge, @knuton and me talked about some changes and fixes that will come soon so we can deploy. |
|
Yes, DNS record needs to be added. |
|
The docs are still available at https://github.com/chaplinjs/chaplin/tree/master/docs, but they are a bit confusing because of the new Jekyll markup. We need to investigate how to transition to the new domain while supporting the old URLs. |
|
Should it already work when the domain points correctly? I tried to make such a HTTP request but got a Forbidden. |
|
I’ve created (name server: superns1.9elements.com) |
|
gh-pages is not needed for repos which are in .github.com repo |
|
I can see the docs here http://chaplinjs.org/chaplin/ but not at new domain |
|
The entry looks fine. The |
|
For your question about chaplinjs.github.com, see https://help.github.com/articles/user-organization-and-project-pages. |
|
Any idea where I have to put the CNAME? |
|
It’s on! Hooray! |
|
Is it safe to add a |
|
That is definitely safe. I am not sure to what extent they should be tailored to be read directly on GitHub, but this would surely do the job. |
This is a proposal on how to give the documentation for Chaplin some more glory, while still keeping them close to the source for convenient maintenance. It also builds on @paulmillr's work to have bi-lingual (CoffeeScript/JavaScript) docs.
It would be nice to have some more freedom in the presentation of the docs, make browsing them more convenient, and offer an option to switch between the two languages to reduce visual noise.
At the same time, as @molily told me, an earlier attempt at keeping the docs in a separate repo has been abandoned due to trouble with keeping source and documentation in sync.
My basic idea for remedying both is to leave documentation source files where they are now, but use GitHub Pages to make them available to the public. Using Jekyll, the existing files can be transformed into a more easy-to-use, more browsable collection of docs, without having to change too much.
You can see my first steps into this direction here: http://knuton.github.io/chaplin/chaplin.collection_view.html
I have slightly adapted the styles from chaplinjs.org and added the option to choose one's preferred language at the top of the page (persisted in localStorage).
The individual doc files would not have to change much in order to accomodate this change: 06ea47f#L4R0
Another addition I would like to make is to add a sidebar or some other option to jump between modules quickly.
The main benefits I expect from this are
I'd like to hear your feedback. Paul has already expressed his concerns in an inline note. Paul, can you explain how this suggestion would be harder to maintain compared with the current setup?