Let's Make a Framework: Project Websites
frameworks
tutorials
lmaf
documentation
Welcome to part 48 of Let’s Make a Framework, the ongoing series about building a JavaScript framework.
If you haven’t been following along, these articles are tagged with lmaf. The project we’re creating is called Turing.
Hosting Documentation
GitHub will host open source projects for free. It renders README files on the project’s page, and works with textile, markdown, and probably more formats. Most open source projects I encounter include a nicely formatted README with code examples.
But GitHub allows us to go beyond that with the GitHub pages feature. This can be used to host the documentation we generated with dox last week at http://username.github.com/project-name. In this case it’s at alexyoung.github.com/turing.js/.
GitHub’s documentation on Pages is actually very good, but I’ll walk through how I set up Turing’s documentation here as well. Pages will look for a gh-pages branch in your project. It would be possible to fork the entire project, but I created a clean branch:
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx
Then I added a quick Jakefile that downloads Turing’s latest documentation from GitHub:
var exec = require('child_process').exec;
desc('Updates the documentation from GitHub');
task('docs', [], function() {
exec('curl -O https://github.com/alexyoung/turing.js/raw/master/docs/index.html');
});
Your projects might require totally unique hand-written documentation — in which case use a clean branch — or you might have a copy of your main branch and just generate an index.html file (many projects work this way).
Next I pushed the branch to GitHub:
jake docs
git add .
gc -m 'Created gh-pages branch with documentation and a Jake task to fetch the documentation from GitHub'
git push origin gh-pages
# Switch back to master
git checkout master
GitHub then sent me a notice to say the documentation was generated.
These branches can be viewed on GitHub:
Registering a Domain Name
Another nice GitHub Pages feature is custom domains. I registered turingjs.com and set up a CNAME file in Turing’s gh-pages branch. The CNAME file just contains turingjs.com, then I set up a record pointing the domain to 207.97.227.245 — this is an IP address at GitHub.
I bought this domain and configured the DNS through NearlyFreeSpeech.NET, a company recommended to me by a friend. They have a fairly unique pricing policy which seems appropriate for an open source project, so check them out if you’d like a domain or some hosting for your own work.
A Simple Project Site
I’ve adapted the documentation generated by dox to include some introductory text with code examples. In general when writing your own sites and READMEs, consider including the following:
- A link to the source code
- Code examples
- A link to documentation
- License information
- Installation advice
- Planned updates
- Contribution guidelines
- Social links: Twitter, Facebook, Google Groups, email, etc.
This will make it easier for people to use your project and contribute. It also makes it easier for journalists who want to write about your project.
I’ve started including a list of recent updates in some of my open source projects. Technically this information can be obtained from the version control system, but it’s sometimes useful to draw attention to certain updates.
