termtosvg – record terminal sessions as SVG animations

termtosvg (GitHub repo) is a handy little tool that makes recording animated sessions in the terminal as simple as humanly possible. Instead of generating heavy graphics or video animations, this tool creates SVG files, which are a lot smaller and easier. There is also a selection of themes to choose from.

Th resulting SVG files can be used as quick demos and guides in READMEs on GitHub, or as tutorials for your application’s website.

Markdeep – Markdown on steroids

Markdown is of the best formats for writing documentation. It’s intuitive, cross-platform, and can be read or written without any special tools. But it does have a variety of limitations too (no includes, no special formatting for advanced things like charts or formulas, etc).

Markdeep is one of the tools that tries to extend Markdown and solve some of its limitations.

Markdeep is a technology for writing plain text documents that will look good in any web browser, whether local or remote. It supports diagrams, calendars, equations, and other features as extensions of Markdown syntax.

Documenting lists with Swagger


Swagger is a great tool for documenting APIs.  Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation.

We use Swagger a lot at work.  We’ve even pushed the bar slightly, but automatically generating the API documentation on the fly, to match the rest of our Qobrix functionality.  Whenever you change the database schema or the configuration of the fields, the changes are also reflected immediately in the API documentation.  And it works great!

One of the things that we haven’t done though until very recently is the documentation of the list fields.  Swagger provides the enum to document the values that can go into the field, but it’s not very helpful, when the values are not obvious.  Country codes and currency symbols work well, as they are common knowledge.  But if you have something custom, there needs to be a set of labels associated with the set of values.

The other day we decided that something is better than nothing, and added the documentation of the values as part of the field description (the property is described on the same page as enum above).  Here’s the Pull Request with the tiniest of changes.  And here’s how it looks in Swagger:

I admit, it’s not the prettiest of things, but at least the hints for the developers are there.  Also, since the list of labels uses a specific format, it’s quite easy to parse it out of the Swagger JSON automatically and reuse in third-party applications and services (like a website, connected to the system via the API).

While browsing around, I’ve also noticed that Swagger is growing and expanding. There is a new version of the specification – version 3.0, which has also been re-branded as OpenAPI Specification (see OpenAPI Initiative).  Here’s a great blog post that describes the differences between this and the previous versions, and here’s the migration guide for those who need it.

If you are working with PHP, zircote/swagger-php is the way to go.  It already even support the version 3.0.  If you are using the CakePHP framework, alt3/cakephp-swagger is the plugin for you (version 3.0 is not yet supported, but I’m sure it’ll get there soon).

Kitab – documentation rendering and testing tool for PHP


Kitab is a handy tool for PHP developers that helps with two things:

  1. Render static HTML (with added search) from the doc-blocks in source code.
  2. Unit test the examples that are in the doc-blocks.

There are a number of tools that do the first one (phpDocumentor, Doxygen, Sami, etc).  However I don’t remember seeing anything that accomplishes the second task.

Zeal + Vim = offline CakePHP (and other) documentation


As any long time Vim user, I’m constantly looking for ways to tweak and improve my text editor configuration, and make me even more efficient.  Today, I came across a very handy addition – Zeal – an offline documentation browser for developers. (Thanks to this blog post, which also mentions Dash as an alternative for those of you on the MacOS.)

With Zeal, you can download a whole lot of documentation sets for pretty much any web development technology out there – programming languages, frameworks, libraries, tools, and more.  And then you can easily integrate Zeal with whatever text editor or IDE you are using.

For Vim, there are, as always, several options.  Some of them are listed here. I personally opted for the Zeavim plugin.  The installation is straight forward and everything works out of the box.  After giving a quick try, I decided to adjust my .vimrc file to use CakePHP framework documentation together with the PHP programming language documentation whenever I’m working with any PHP file.  Here’s what I had to add:

" Zeal offline documentation
let g:zv_file_types = {
       \ 'php': 'cakephp,php',
       \ }

Now, whenever I edit a PHP file and hit “,z” (I use comma as a leader, by the way), Zeal window pops up with the relevant documentation search.

It’s super fast. It works offline, and it’s awesome!