New documentation site

[mroderick]

This is a legacy issue that is just around for the sake of tracking progress on Sinon 2. See #1189 #1220 for actual documentation subtasks that are yet to be done.

See #966 for an overview of all the remaining work on Sinon 2.

---

I think we should use http://jekyllrb.com for generating the new site. I realise that it's not JavaScript, and I am fine with that. I don't need everything to be JavaScript. Most contributors are unlikely to need to run it, and for those that do, it's fairly easy to get it running these days.

Jekyll uses GitHub Flavoured Markdown, which should make it instantly familiar to everyone that contribute to open source these days.

Versioning

The strategy for versioning the documentation is described in docs/README.md.

Assumptions and requirements

• Assume HTTP/2 → skip concatenation, asset bundling, sprites, sharding, etc.
• Avoid build steps, we don't know the build/deploy pipeline yet, and fewer moving parts, means less support and easier maintenance → plain CSS, no pre-processors
• First version should have no JavaScript, just like the current site
• Build for modern browsers → Sinon.JS is a development tool, developers have modern browsers
• Developers are likely to use their desktop browsers to access the site, not their smart devices or in car entertainment systems → Responsive design is a nice to have, not a must have
• We really don't need more maintenance work → Use well documented dependencies (Bootstrap welcome) in stable versions only

Requirements / To Do

• Basic site in Jekyll that displays all the content currently in docs, for both 1.7.x and 2.0
• Jekyll should generate navigation from directory structure in docs/releases, see docs/README.md
• Bonus credit: accessiblity

Please post suggestions and comments!

[fatso83]

This seems nice, but the README link is wrong. Should be https://github.com/sinonjs/sinon/blob/master/docs/README.md

[fatso83]

And the TODO mentions Metalsmith, not Jekyll.

So to test out how the docs will look one will need to have Jekyll installed, and then run some kind of build script. Seems fine.

[mroderick]

This seems nice, but the README link is wrong. Should be https://github.com/sinonjs/sinon/blob/master/docs/README.md

Fixed, thanks

[mroderick]

And the TODO mentions Metalsmith, not Jekyll.

So to test out how the docs will look one will need to have Jekyll installed, and then run some kind of build script. Seems fine.

I've pushed a new commit that updates the TODO.md. I'll try to get a branch together for this work

[fatso83]

@mroderick I was unable to update the site after shipping 1.17.4 last night, getting a java.lang.NullPointerException from the leinigen build script. As I am really not to keen on debugging the Clojure code I would rather help you out building the new tooling for a new site. Is there any way one could contribute?

[fatso83]

Thinking that working is better than perfect, I want to start contributing on this task. I was thinking of creating a sinonjs.github.io repo and start pushing the output from Jekyll there. Until someone with better graphical design skills than me comes along I might just copy the existing look. When this reaches feature parity with the existing we will ask Christian to switch the DNS records for the main domain over to our GitHub site. Seems like a plan?

A few concerns:
what is happening with the current sinon-docsrepo? Should I update the README to state that improvements should go to the main sinon project, and just close the issue tracker and pull requests? Or just delete the repo? The latter seems a bit drastic, perhaps?

Should all the build scripts go into this project, or should we keep them separate (in sinon-docs)?

[fatso83]

I think maybe the actual build scripts could well live in the sinon-docs project, while the raw data will be kept in the sinon project (possibly as a git submodule in sinon-docs?). That way all the scripts and whatnots could be kept out of the main sinon repo.

[jonnyreeves]

@fatso83 sounds like a good plan to me; I'm happy to contribute to the docs once we have a pipeline setup. Also, IMHO there is a great deal of value in keeping the documentation source (ie: md files) in the same repo as the project's source code.

[fatso83]

OK, so I have been reading up on how to achieve Morgans intended goals, with the main parts being

• simplicity
• automatic builds
• no build pipeline

The last part seemed a bit hard to fulfill, given that Morgan mentioned using Jekyll (which does have a build step), but by utilizing GitHub pages it is not a step we need to execute ourselves :-) I know that Morgan mentioned avoiding Sass, but since GitHub pages supports it I don't see why we need to avoid it completely ... Other than that I fully agree. Anyway, I am thinking a release build of Sinon, including building new docs, will follow these steps (assuming ./publish 2.0.3 has been run).

1. npm test
2. [[ -z $(git status -s) ]] #check that there are no uncommitted changes
3. ./build.sh
4. mv pkg/* docs/releases/current/build
5. git commit -m "Add packaged files"
6. npm version $VERSION #Also tags and updates package.json
7. git push --tags
8. npm publish $VERSION
9. git clone --depth 1 [email protected]:/sinonjs/sinonjs.github.io __tmp_docs__
10. cd __tmp_docs__ && git commit -m "Build docs for $VERSION" --allow-empty && git push
11. #various cleanup

The magic here is of course step 9 and 10 which will basically just push a new empty commit to the GitHub pages repo and thus trigger a rebuild of the site.

This means a new release of sinon with new docs could be down to nothing more than npm create-release 2.0.3

[jonnyreeves]

@fatso83 I'm not too familiar with Jekyll, but don't we need to copy the markdown files from docs/current into __tmp_docs__ between steps 9 and 10?

[mroderick]

I know that Morgan mentioned avoiding Sass, but since GitHub pages supports it I don't see why we need to avoid it completely

There were a few motivations for this:

• ease of maintenance
• easy to get started as a contributor

[fatso83]

@jonnyreeves No, as I previously wrote that we could include the main sinon repo as a submodule. GitHub Pages pulls in all submodules when a build is triggered. You are right in noting that I did miss a step, as I forgot the step we do cp current $VERSION ...

@mroderick : as SASS is usually employed to ease maintenance, I am not sure I agree, as there would be less code to write and no additional build steps, but I am totally following you on the second point for this project to lower the bar. Some people could easily start doing Fourier transforms in the Sass code Ana Tudor style, and we have no need for that kind of complexity 😄 GH Pages does not currently support http pipelining, so using a main.scss could perhaps be employed to bundle css (if size should require us to split up the css into several files). A few @import statements shouldn't stop anyone from contributing.

[mroderick]

@fatso83 I never imagined using github pages, that was your idea :)

[spinningarrow]

I came across https://read-the-docs.readthedocs.io/en/latest/index.html recently (they provide documentation hosting by automatically building it from a git repo from what I understand) - would this be something useful for Sinon docs?

[fatso83]

@spinningarrow Good suggestion, but I think we want to be able to control the looks of the site. After talking to Morgan it seems we will continue hosting a web server ourselves, so readthedocs and GitHub Pages is out.

[fatso83]

Closing this as we have both this, #1189 and #1220 for tracking remaining work. It is hard to get an overview this way. I'm updating #966 as well.