Developer documentation with LaTeX: Workspace and tools

In my previous post, I made the case that developer documentation was useful and that it could be easily done with LaTeX, given some basic structure. Although LaTeX has the same advantages as any code because of its abstraction from the final document, it also has its downfalls. Probably the most repulsing to newcomers is the lack of feedback over what the document looks like in its final form. There exist a couple of tools such as TexMaker, but I found that taking the road to create my own editor-like environment has been more simple and has given me more control over what I wanted to do: write developer documentation. This short entry will try to show how easy it is to integrate LaTeX editing with feedback with remotely any editor using the structure already presented.

The right things at the right place

One thing TexMaker and the likes does well is to provide a preview of your document in a secondary panel. One thing it doesn't really do is... well everything not LaTeX. When working on a software project, our editing tools will likely be an IDE or a multi-purpose text editor which provides some linting, macros and code coloring. Because LaTeX is code after all, working with the same editor would alleviate pain in our duty to keep the documentation up-to-date.

I suggest in this case we use the open source text editor Atom I already mentioned in my previous post. It has the major advantage that it is extensible and is mostly lightweight. Bonus point to the default dark theme which is a bit softer on the eyes. Other popular editors can be used, as long as they provide some level of coloring and Makefile-building feature. Some Atom packages I use for making the work with LaTeX somewhat easier are the following:

• language-latex
• latex-autocomplete
• build
• dictionary (for Mac folks)

The two first ones are used to while writing LaTeX documents, giving you nice and clear distinction of commands with coloring, bolding and italicizing fonts in addition to speeding up start/end blocks by simply having to start the first letters "begin", hitting enter and continuing with the type of the block. Next is the build package which serves the obvious purpose of building our document. Build also needs some configuration, which if you use the Makefile I provided in my previous post will be very simple. So simple, in fact, that it contains only one line:

This file ".atom-build.yml" needs to live in the project directory, for example a folder called "doc" in your project. If you happen to already use the build package to build your software project, you can always open the documentation directory separately (as an additional project directory) and open the appropriate files from there. To build, the standard command is F9.

To mimic the side-by-side editor and preview, it is simple to set the editor to the left of the screen (if you have snapping feature in your window manager, that's a piece of cake) and whatever PDF reader pops-in to the right, or more usefully to another monitor if it can be spared.

If you happen to use an IDE, it should be fairly simple to create a custom build target with makefile that will launch the same command as the one contained in the build config file: make build-run. Remember to uncomment the line corresponding to your platform to use the correct launching application. If you are in a multi-platform scenario, it is fairly trivial to automate the execution of the correct line with simple IFs.

What about the documentation itself?

The right tools are nice and efficient, but they don't provide any mean to write good documentation. This will be the subject of the next entry and I'll try to provide some more hints on how LaTeX can be used within the context of software development, such as using htlatex rather than pdflatex to produce HTML documents rather than PDF for easier consultation in online repositories.