If there’s one thing I hate more than tracking down bugs, it’s documenting code. It takes forever, it’s almost a project in itself, and I never seem to factor it into my project lifecycle.
Setting out to solve that problem for me, and anyone else whose life is too short, is Couscous. Couscous takes markdown files and converts them into professional standard HTML docs that colleagues, or fellow developers, can easily follow. You can preview the resulting site on your local machine, correct any issues, and then deploy straight to GitHub where it will be hosted for you.
If you’re working with remote teams, or just hate explaining code to other people, Couscous will make communicating your APIs a whole lot faster.
Installing Couscous
The first thing you need to do is ensure that your local system is running PHP 5.4 or later. Next you need to ensure you have Composer installed, if you don’t have it already you’ll find installation instructions here.
Once Composer is installed you can install Couscous like so:
$ composer global require couscous/couscous
And that’s it!
Using Couscous
Couscous is a dedicated solution for documentation, it doesn’t moonlight at all, so you don’t have to contend with the optional extras some site generators come with; it does one thing well.
There are some basic templates included, or you can build your own and brand your documentation appropriately.
You’ll be pleased to find automatic syntax highlighting, which for me is one of the best features, is included in the basic templates. It’s obviously inefficient to have to markup code examples by inserting spans in code blocks just to pick out variables and so forth, so the automation is a welcome addition.
If you’re looking for the default functionality all you need to do is run this command on your project directory:
$ couscous preview
Then open up http://localhost:8000/ in a browser, and voila! Your docs are ready to review.
Couscous builds documentation from standard markdown files. It will run through the directory and find any *.md files, which it will include in the batch process.
No special markdown is required, and you don’t need to follow any particular directory structure.
You can make as many changes as you like to your original markdown, then run the preview command again. Rinse and repeat until you’re happy.
Deploying documentation
Once you’re satisfied with your documentation you’re ready to go live. Then, simply run:
$ couscous deploy
Couscous will gather your files and publish to the gh-pages branch of your Git repository.
Why Couscous?
Couscous is the simplest solution I’ve come across in some time, for rapidly building documentation.
If you need to build online docs for any project, or even for your own recollection, Couscous is a streamlined and elegant solution that imposes no restrictions on you. It can save you hours, allowing you to redirect all your effort into the code you’re documenting.
Whether you’ve always recorded everything you code, or you’re just starting out documenting your first complex project, with Couscous the process is both fast and painless.