Software documentation with markdoc 5.0

Abstract

markdoc is a general-purpose literate programming package for generating dynamic documents, dynamic presentation slides, Stata help files, and package vignettes in various formats. In this article, I introduce markdoc version 5.0, which performs independently of any third-party software, using the mini engine. The mini engine is a lightweight alternative to Pandoc (MacFarlane [2006, https://pandoc.org/ ]), completely written in Stata. I also propose a procedure for remodeling package documentation and data documentation in Stata and present a tutorial for generating help files, package vignettes, and GitHub Wiki documentation using markdoc.

Developing, maintaining, and hosting Stata statistical software on GitHub

“…In the '90s, the emergence of the Internet made collaborations between geographically separated developers possible (Raymond 1999). This was particularly important for open-source software development, which survives on volunteers contributing during their spare time (Hars and Ou 2002;Raymond 1999Raymond , 2001. In contrast to the early skep-ticism (Lewis 1999), collaborating on open-source software has become a social norm, as implied by the enormous community of sites such as GitHub and Stack Overflow (Vasilescu, Filkov, and Serebrenik 2013).…”

“…The latter includes the code for rebuilding the package installation. Generating this file is recommended, especially if the package documentation is generated by the (Haghish 2016) package, a procedure that is thoroughly discussed elsewhere (Haghish 2020). Simultaneously, the command also examines whether each filename has been published elsewhere, whether on the SSC Archive or GitHub.…”