Google+

Automatically publish documentation using Autodocs

I have been working on a NodeJs module quite diligently over the past couple of weeks, and I have finally cut a release that I am satisfied with releasing for wider use.

NPM

Build Status Coverage Status

Install it as a development dependency

npm install --save-dev autodocs

... and then add an autodocs hook to the scripts section of package.json:

"scripts": {
  "autodocs": "node ./node_modules/autodocs"
}

... and then invoke the autodocs hook in .travis.yml

after_success:
- npm run autodocs

Finally configure autodocs by specifying environment variables, also in .travis.yml. The only compulsory one is GH_TOKEN, a Github access token, which you will need to obtain from Github, and then encrypt using Travis.

Note that autodocs does not generate any documentation itself - it is designed to publish documentation from a continuous integration server. It expects there to be a hook named generatedocs the scripts section of package.json.

That's all. Commit and push to your master branch, and you should get your documentation published to:

http://GH_USER.github.io/GH_REPO/api/VERSION

Documentation

There are quite a few options that you can configure.

For example, you can set it up such that:

  • the URL it publishes to is differrent,
  • it publishes to a different repository,
  • it publishes when a different branch, e.g. develop is pushed instead
  • it publishes when a release is cut - a tag is pushed

For these, and more options, see autodocs' own documentation, which, you guessed it, is published by autodocs itself.

autodocs documentation

Roadmap

At the moment, autodocs only supports on CI environment - Travis - and one publishing environment - Github Pages. Other CI environments and publishing environments can also be supported.

These, and other issues, can be found at autodocs roadmap

Contributions are most welcome!

First contribution to Rust Compiler

I made my first contribution to the Rust compiler yesterday evening!

Rust logo

The learning curve was quite steep, so I started with something relatively simple - adding a detailed error message for one of the errors thrown by the compiler.

If only for my own future reference, I detail the entire process below: Compiling --> Verification --> Submission --> Acceptance --> CI

Compiling

Compiling rustc for the first time:

git clone https://github.com/rust-lang/rust.git
cd rust/
./configure
make -j 4
sudo make install

Now edit some source code to add the new feature or fix the bug.

Re-compiling

After making some changes:

make -j 4 rustc-stage1
export PATH=$( pwd )/${PLATFORM}/stage1/bin:$PATH
export LD_LIBRARY_PATH=$( pwd )/${PLATFORM}/stage1/lib
which rustc
rustc --version

(The value of ${PLATFORM} should be obtained from the build output, e.g. x86_64-linux-gnu or x86_64-apple-darwin)

Instead of compiling the entire project all over again, which will take extremely long, simply compiling one of the compile targets (rustc-stage1), and adding the relevant output files to the executable and library paths is a much quicker alternative.

Verifying the fix

In my case, the change was to add the detailed explanation message for a particular error message. To test this, run the --explain command:

rustc --explain E0265

Which should output the following;

  This error indicates that a constant references itself.
  All constants need to resolve to a value in an acyclic manner.

  For example, neither of the following can be sensibly compiled:

  ```
  const X: u32 = X;
  ```

  ```
  const X: u32 = Y;
  const Y: u32 = X;
  ```

Submitting the patch

Once the patch is OK, fork the repository on github, commit and push to your fork on a new branch, and then submit a pull request for your patch.

Fork the repository on github

Switch the remotes such that the upstream points to the rust-lang organisation's repository, and the origin points to the your forked copy of the repository.

git remote add upstream git@github.com:rust-lang/rust.git
git remote remove origin
git remote add origin git@github.com:${GH_USER}/rust.git

Commit and push:

git checkout -b ${SOME_BRANCH_NAME}
git add src/
git commit
# Enter a commit message
git push origin ${SOME_BRANCH_NAME}

Visit the main repository on github again, and click on the link for "compare and create pull request".

This results in a pull request: github.com/rust-lang/rust/pull/24894

Patch acceptance and Continuous Integration

Someone from the core team or reviewers team for Rust will get assigned to review the pull request, and if it passes their review, they will add a comment like this:

@bors: r+ ${COMMIT_HASH}

This triggers the Bors Github bot, and the patch is added to the Homu build queue. Visit the build queue, and find your patch on the list:

buildbot.rust-lang.org/homu/queue/rust

Note that you will find that the project contains a .travis.yml file. This led me to believe, initially, that Rust uses Travis as its continuous integration system. However, it only uses Travis for make tidy, which is essentially a linting task. I assume that this is because compiling rust takes a lot longer than the maximum of forty minutes per build allowed by Travis. The actual CI infrastructure for Rust consists of a couple of Github bots

Experience

As mentioned earlier, it was an extremely steep learning curve.

It takes extremely long to compile the project from scratch. Even just the rustc-stage1 target, takes ages. This is quite a big inhibitor for further contributions, as one would have to have access to an extremely powerful build machine in order to attain a reasonable amount of productivity developing Rust itself. If possible, I would like this to change. Perhaps break the project up into several smaller ones, and make it possible just to recompile the ones that changed.

This problem spills over to the build queue as well. It took just under two days for my patch to get compiled and tested by the continuous integration system, and get merged in.

Luckily I had a couple of experienced guys to guide me - thanks to Michael and Huon for walking me through the innards of librustc and libsyntax!

Now your turn!

If you are interested to get your contributions on, this issue is a good place to start.

At first I attempted to fix this one, however, it was beyond my current Rust skills, so I have had to let that be. Double points to anyone who tackles that!

SVG 9-slice scaling

SVGs are a thing.

9-slice scaling is a thing.

Put the two together, and ...

Turns out that 9-slice scaling isn't so easy to do in SVGs, because SVGs use a coordinate system where it is not possible to specify dimensions in terms of both percentages and fixed values. That is exactly what you need though, for 9-slice scaling!

Fortunately, the SVG specification includes an escape hatch of sorts, <foreignObject /> which allows you to embed something other than an SVG within itself. We can use this to put in a HTML fragment, which of course can make use of CSS properties to specify dimensions in terms of both percentages and fixed values! Once we have got the right positions and size using HTML/ CSS, we can then place an SVG within it.

That sounds extremely inefficient, doesn't it? Turns out there is a neat little trick in play here, enabled by <symbol />, <use /> and xlink. In the outer SVG, you can define a <symbol />, which contains the full graphic, in a <g />, which needs to be sliced. Subsequently define nine <symbol />s each of which have a viewBox to restrict their display to a particular slice of the full graphic. Within the symbol, we have a <use /> with an xlink to reference the original graphic. This is actually a big deal, because what happens behind the scenes, to make all this work, is that the SVG is only rendered once, and is thus quite efficient, because each of the nine slices do not need to re-render the original graphic. This is not the first time which we will make use of this, because when we use <foreignObject />, which contain inner <svg />s, we have <use /> with an xlink once again, but this time referencing the sliced graphic <symbol />s instead.

It is quite amazing that the reference still works despite going SVG --> HTML --> SVG. Thank you to whoever ensured that this was part of the SVG specification. When I did that for the first time, I held my breath, half expecting it not to work at all!

Enough rambling, show me the sauce!

I have posted the working SVG on this gist.

svg-9slice-scaling.svg

Click the link and open it in a new tab/ window, then resize the window to see what I mean.

... and then Internet Explorer happened

  • Chrome ... check!
  • Firefox ... check!
  • IE ... meh.

A key part in the way this technique works is <foreignObject />. Unfortunately, Internet Explorer does not support this so that goes out the window. If anyone has figured out how to make 9 slice scaling work in IE, I would be most interested!

AngularJs vs EmberJs - A Comparison

So you want to build a single page web application (SPA), and you want to pick a framework to do it with. There are plethora of them out there - TodoMVC lists 15 "pure Javascript" implementations, and a total of over 60 MV* frameworks. How do you confidently pick from them all?

Most would start by reading blog posts and various reviews online, but that only gets you so far, as the majority of them are written by someone who belongs to one camp or the other, and quite often roots very strongly for their chosen framework. It was quite hard to find any objective opinions.

The Book

Faced with this task myself, I began to collect opinions from both sides, and filter out the vitriol. More importantly, I tried out and built prototype applications with them. In light of time, I only did this for two frameworks: AngularJs and EmberJs.

I have assembled what I have learned into a short book, which you can read online, or read as an ebook.

AngularJs vs EmberJs on Leanpub

Do you actually need a SPA?

The first thing you will need to do is decide whether you really need an MVC framework. This boils down to two questions:

  • Do you want "single page", or do you want "application"?
  • Do you want a presentation layer, or do you want the full structure of models, views, and controllers?

If what you are building can be more accurately described as an app than a website, then sure, a SPA framework such as AngularJs or EmberJs is apt. Otherwise, it is probably overkill. For example while you can use AngularJs/EmberJs to create a blog, you are probably better off with a simpler framework or library.

If you wish for Javascript to mostly just do the presentation logic - views and templating - you are probably better off with a framework like Famo.us or ReactJs, as they focus on that exclusively.

Which SPA is best?

Looking online on this topic, most posts fit one of these two categories:

  • Framework X is the best framework because it has these features
  • Framework Y is the lousiest framework because it has these problems

The latter type is even even less helpful when they focus on edge cases, which you are bound to run into in any framework.

Reading these articles might give you some perspective on each framework, but what is lacking is detailed a side-by-side comparison of the parts of each framework. This is precisely what my book does.

However, in this post, we will skip that, and get into the guts of how to make that decision right away. The implied premise of this is that there is no best framework, but there most certainly is a best framework for your particular app.

Here are some questions you may want to mull over when picking a framework.

1. What do you like or dislike about the syntax?

Most of the time, you will be writing code. Therefore syntax matters a lot. Examine the sample code for a router, a model, a view, a controller, and a component. Can you see yourself writing in this style, and do you have a preference for one style over the other?

I feel that it is important to familiarise yourself with what the code looks like before picking a framework, not only because you will be writing it, but also because it gives you a glimpse into higher order functionality from the get go.

For example, you might look at AngularJs' router definition syntax and compare it to EmberJs' router definition syntax; and infer that in AngularJs all routes are flat, whereas in EmberJs routes can be hierarchical. Some further research might indicate that hierarchical routes are indeed possible in AngularJs, but a 3rd party library, ui-router is necessary.

Another example might be that you compare AngularJs' component definition syntax, using directives with restrict, transclude, and isolate scope, to EmberJs' component definition syntax using Ember.Component.

For each of these examples, you can think about it in the context of the app that you plan to build. Perhaps you already know whether your app will need hierarchical routes. Perhaps you already know whether a standard component will do, or if you need a higher degree of flexibility when defining components.

All these sorts of things can, and will cross your mind, simply by familiarising yourself with the syntax when writing code using each framework.

2. What kind of learning curve do you want?

  • If you prefer an easy learning curve up front, and do not mind a steep learning curve later on, then AngularJs
  • If you prefer a steep learning curve up front, then EmberJs

This, of course, does not apply to every one. If you have prior experience with Ruby on Rails, then the learning curve for EmberJs is likely to not be as steep up front. If you have prior experience with Java, then concepts such as dependency injection in AngularJs are going to be familiar.

This is true, not just because of familiarity or similarity in code, but also because of the history and philosophy of the authors, and what they were inspired by when they created the frameworks.

One other thing that you should do, is to check out the documentation for each of the projects. Survey them for their quality: How easy it is to find information about something, and how complete the documentation is. My opinion is that both of them have rather solid documentation - at least they do now - but many others have complained about their shortcomings, so make up your own mind when you take a look.

3. What else do you need to learn or use to become proficient?

In addition to the framework itself, you will also need to learn how to use other libraries or tools, in order to develop your app. You do not necessarily need to use any of these, as both frameworks can be used in their own right. However, in practice, when developing a serious app, this is what most developers use. It is, therefore, a good idea to know what these are ahead of time, before jumping into one or the other.

With AngularJs, you will most likely need to learn:

  • ui-router (an alternative, more power router)
  • gulp or grunt (build tools)

With EmberJs, you will most likely need to learn:

  • ember-cli (a command line utility used to scaffold and build EmberJs apps)
  • broccoli (a build tool)
  • jQuery
  • ember-data (for models and persistence, distributed separately from the main EmberJs)

It is evident that for EmberJs, there is much more to learn to use in addition to the framework itself. With ember-cli however, the flip side of learning one additional tool, is that it makes app development a lot more productive, by allowing you to scaffold part of the app quickly. Therefore there are pros and cons to weigh for each.

3. How complex is your app?

  • Creating simple apps is easier to do with AngularJs than it is to do with EmberJs.
  • Conversely, creating complex apps is easier to do with EmberJs than it is to do with AngularJs.

This stems from something that occurs under the hood in each framework, that you most likely will not encounter when beginning with either framework.

Both frameworks are able to update their views when their models change, and update their models when their views change. This is two-way binding. However, both of them use different means to listen for changes on models. Until Object.observe() lands in the next version of ECMAScript, it is not possible to listen for changes on Javascript objects.

Ember solves this by requiring all models to be wrapped in Ember.Object, and use accessors (get and set) to view and manipulate those properties, attaching the event listeners to the accessor methods. AngularJs allows you to use regular Javascript objects as models, but it keeps a copy of every model, and checks for differences at a regular interval (within its digest cycle) between the model, and the previous copy of it.

EmberJs' approach results in more verbose syntax when manipulating models, but performance does not take a hit as models become more numerous or complex. AngularJs' approach has nicer syntax when manipulating models, but performance takes a hit as models become more numerous and complex.

The problem with AngularJs described above is mitigable, however, it is not easy to do so correctly, as it requires some very in-depth understanding of how the internals of AngularJs work. Thus, when picking a framework, it would be pertinent to lay out the wire frames for each of the screens in the app, and estimate the size and complexity of the models required to be displayed on each screen. If your models exceed 2000 pieces of information (this is only rough number, from Misko Hevery), your choices are:

  • Either choose EmberJs, or
  • become familiar with advanced dirty-checking avoidance techniques in AngularJs.

I have previously written in detail about accessors vs dirty checking.

4. Do you agree with the philosophy of the framework?

This is quite a fundamental question, and yet, largely a matter of personal preference.

AngularJs is an extremely flexible, and unopinionated framework. Take, for example, that it provides six different ways to define a service on a module (one of which is confusingly named "Service"). This, and many other instances of an abundance of choice, means that there are many different ways to accomplish the same task, and thus developers tend to go about doing things in different ways.

EmberJs, on the other hand, is a stark contrast to this, in that it is extremely opinionated. In most things, EmberJs explicitly defines the one correct way to do something, and everything else that you try simply will not work properly. A great example of this is the naming conventions imposed by the framework - if you name your controllers something other than what is expected, the controller is simply ignored! While this is a major stumbling block when first starting out with EmberJs, it also ensures that most developers stick to doing things in the one prescribed way.

This boils down to the level of abstraction. Those who prefer AngularJs tend to be those who prefer a lower-level framework, as it affords them more flexibility, and is closer to the metal. Those who prefer EmberJs tend to be those who prefer a higher-level framework, as they prefer the consistency and ease of collaboration that comes with a lack of flexibility.

5. Do you like where the framework is heading?

Both AngularJs and EmberJs are in their 1.x versions. Their authors have recently released their vision for their 2.0 versions.

In summary, EmberJs looks like it is going to be quite stable in its transition from 1.x to 2.0, with very few breaking changes. AngularJs, on the other hand looks like it is going to be a complete rewrite, and the transition going from 1.x to 2.0 is going to be a painful one for most developers, with many breaking changes.

Round up

So which should you pick? Answer the questions above, and you will know which on you prefer. If you are still undecided, select one or two screens from your app, and develop them using both frameworks, keeping these questions in mind, and then decide!