Saturday, March 22

Generate PDF with Sphinx Documentation System

Documentation

One of the most important things in any project is documentation, yet it is usually the last thing if it is done at all.

I've recently change jobs and in the new company we create SDKs for different platform and languages. We are lean and fast and do a lot of changes quickly but we realize we better get our documentation abilities agile as well as our development skills.

What is Sphinx?

After evaluating several documentation tools I've found Sphinx. This is the tool used for Python documentation. The reason it looks best for me is that it is a mature project, it has a notion of version which is important for documentation as it is important for the software itself. It has many extensions that are not required for me now but I'm sure will come in handy later.

Output to HTML

The first and most important requirement is that the tool will be able to output HTML based documentation. This is because we plan to have each specific platform's SDK created in it native tool and use HTML as the one unified languages to connect them all together (thank you hyperlink).
If you follow the quick-start application of sphinx all you need to do to create HTML docs is 

make html

Output to PDF

This is not a must but it will be nice to be able to create PDF documentation both for download and in-browser reading. The problem is that when I run make latexpdf I got this error:

make[1]: pdflatex: No such file or directory

After google it for a bit I was able to find a post about how to generate PDF  using Sphinx. From there I was able to find the line after pdflatex command as follows:
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
Using this I was able to find MacTeX-2013 Distribution which is Mac package for TeX tools. The problem is that the main download is 2.2GB download but a few clicks away is Smaller packages for only the essential tools.

Wednesday, December 4

SproutCore Web Application Development - Free eBooks

A new book about SproutCore has been published and I've has the honer to review it. The book name is SproutCore Web Application Development and it explain everything you need to know to get started with SproutCore.
The debate about which MV* JavaScript framework is the best has raising flames. SproutCore does not get the attention is deserves as a proven stable framework that support sites like iCloud (used to be known as MobileMe).
One area in which SproutCore did lack was documentation. This problem has been fixed and this book is one peace of prof.

I'll be publishing posts next week, anyone who will post a comment in those posts will be candidate for FREE copy of SproutCore Web Application Development book

Monday, September 9

1111 MSTestRunner Users

I'm happy to see today that MSTestRunner Jenkins Plugin I wrote and use every day has pass the 1K users this month.

Many thanks to all the users and specially to those who left comments explain how to improve it.

Have fun using it and keep on testing.

Tuesday, August 27

CouchDB Many To Many Joins

I'm on the process of converting our application from using SQL Server and Entity Framework 5 to CouchDB. I'll explain the motivation in separate post.
This post is about entity relationship of Many to Many.

CouchDB does not have entity relationship the way RDBMS does. But it's not hard to create them.
Our application is multi-tenant and each user in our application can be allowed to access many tenants. This makes a many to many relationship between users and tenants.

First thing is modeling users and tenants as documents. I've took the very simple approach of creating a document for each user and each tenant. User document have field call $type with value of "user" and Tenant document have field call $type with value of "tenant". Simple :)
I use dollar sign in the field name to make it very clear it is not a native field of the document itself, it is a "system" field.

The way I've decide to model this relationship is by holding array of User document IDs inside the Tenant document. Generally you will want to hold the array on the side that is least likely to change.

The documents will look something like this:

{
  • _id"54",
  • _rev"3-53c1c569bc6c316d4d29f20c47f05184",
  • $type"user",
  • username"a@b.com",
  • firstName"ido",
  • lastName"ran",
  • email"a@b1.com",
  • passwordSalt"AABBCC=",
  • password"123HASH"
}

{
  • _id"20121207153325-Ido-Test",
  • _rev"2-8d9cb3b070a062d9a65ed22fa3f7bf9b",
  • $type"tenant",
  • users:
    [
    • "54",
    • "63",
    • "84",
    • "124"
    ],
  • name"Ido Test"
}

Selecting the join of both users and tenants is done in two different views, one for selecting tenant(s) and their related user(s) and the second to select user(s) and their related tenant(s).

In order to select user and the related tenants we use CouchDB "Join" view as explained by Christopher Lenz:

function(doc) {
  if (doc.$type === 'user') {
    emit([doc._id, 0], null);
  }
  else if (doc.$type === 'tenant') {
    for (var i in doc.users) {
      emit([doc.users[i], 1], null);
    }
  }
}

In order to select tenants and the related users we use feature of CouchDB called Linked Documents. The feature allow us to emit values of structure { _id: "linked-document-id" } which allow us to later query the view with include_docs=true to select in one GET all the documents including the linked documents.

function(doc) {
  if (doc.$type === 'tenant') {
    emit([doc._id, 0], null);
    for (var i in doc.users) {
      emit([doc._id, 1], { _id: doc.users[i] });
    }
  }
}

In conclusion, it's pretty easy to have many-to-many relation in CouchDB. Storing the relation in one type of document gives some level of integrity but not transactional integrity.
The same views can be used to have One-To-Many relation but that will be in another post.

Thursday, July 11

MEF2 in ASP MVC4

I've search the internet for the way to integrate MEF 2 with ASP.NET MVC 4 and the answer was hard to find.
Finally I found Alt.Composition.Web.Mvc (1.1.17) by nblumhardt. For detailed instructions please see his GitHub repository,

I've use MVC with MEF for a while now but I've used CodePlex bits until now.
Finally I've upgrade our web application to use .NET 4.5 and I wanted to use the new lightweight MEF features as well as application/request scope.

I hope this will answer the questions to others looking for the way to integrate MEF with MVC.

Saturday, June 29

ProjectConfigTransformFileName - Web.Config Transformation

The Need
We start to use AppHarbor .NET PaaS to deploy our web-application.
Because we still have another instance of the same application running in shared hosting provider we needed a way to support both deployment from the same code-base.

The Problem
Visual Studio support different configuration for project out-of-the-box. The two default configurations are Debug and Release. In web projects you also have a matching web.config transformation file for each configuration, that is web.debug.config and web.release.config. Each of them contain only the parts that need to change for each configuration.
I want to have a third web.config transformation with AppHarbor specific configuration without having a new project configuration.
Visual Studio does not support this setup, but MSBuild does.

Why?
I choose not to add a new project configuration, even though it's the route Visual Studio takes you, because it will mean that our team will have one more thing to learn, one more thing to maintain and one more thing that can go wrong.

The Solution
After some digging into Microsoft.Web.Publishing.targets that is located in C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\Web in my dev machine I found the MSBuild variable name ProjectConfigTransformFileName.
Microsoft did a great job of convention over configuration with this script. The convention is to use the web.config transformation name web.[configuration].config but if you specify ProjectConfigTransformFileName it will use that one over the convention.

Since we use Jenkins as CI server we simply pass one more parameter to the MSBuild /p:ProjectConfigTransformFileName=web.release.appharbor.config and now everything works exactly the same beside the fact we use AppHarbor web.config transformation.

Wednesday, June 26

Portable Class Library on Jenkins CI

Like any good developer I try to keep projects organized. Today we finish the first release of our globalization library which we put in a Portable Class Library (PCL) so it will be easy to use it in different projects.

When Jenkins pull the work and start to build it it compline about build errors we did not see on our development machines.

The first error was error MSB4019: The imported project "C:\Program Files (x86)\MSBuild\Microsoft\Portable\v4.0\Microsoft.Portable.CSharp.targets" was not found. Confirm that the path in the declaration is correct, and that the file exists on disk.

We did not install Visual Studio on our Jenkins server so the same way I handle previous problems with target fiels I start by simply copy the target files from my development machine to Jenkins.
This didn't solve the problem just led me to the next problem: error CS0234: The type or namespace name 'Linq' does not exist in the namespace 'System' (are you missing an assembly reference?)

Little digging in the on the web and I found that this time Microsoft make our life easy and have a tool to install PCL tools on build machines.

Cross-Platform Development with the .NET Framework is the title of the document inside the MSDN website. There you can read all about cross-platform development for .NET and specifically download the Portable Library Tools and install it with the switch /buildmachine

There you go, PCL on your Jenkins Build machine made easy.