Generating sthlp Help Files

Stata has a markup language called smcl which is used for organizing the outputs as well as Stata documentation. While the smcl language is very capable for styling a document, however, it is rather complex and fairly, not very friendly to human eye. Nevertheless, writing a decent help file is even more important than writing a good program because a good program will never be complete without documentation.

Furthermore, when using a site such as GitHub for developing and maintaining a project, it becomes important to also write some documentation about your program on GitHub as well. Every GitHub repository has a Wiki which can host the documentation of the software, all written in Markdown. But doing so can be very time consuming particularly because you also need to write and update the Stata documentation written in smcl.

So what can we do to simplify these tasks? I will have two suggestions:

1. simplifying the markup language used for Stata documentation to make it easier to read and write for humans
2. use a markup language that is know to both GitHub and Stata, so that the same documentation can be hosted on multiple platforms

The solution provided by markdoc package

markdoc has a built-in Markdown to smcl translator. In other words, it can translate Markdown files to smcl. Therefore, if the documentations are written in Markdown format, the same source can be used to write Stata help files, GitHub documentation, as well as HTML or PDF package vignettes. This will also significantly simplify the efforts you put into documenting your software. In this section I will explain how you can use markdoc for software documentation within Stata