mkdoc::mkdoc

NAME

mkdoc::mkdoc extracts Markdown documentation from source code files written programming languages like Tcl, Python, R, C++, ... and optionally convert them to HTML or any other document format for instance using pandoc. This package is now part of Tcllib.

DESCRIPTION

Source code documentation tool using Markdown as markup languages directly inside the code. It support programming languages like Python, Tcl, Perl. Markdown Syntax is just prefixed with a #'. Also languages with multi line comments like C++ are supported, just use inside the /* ... */ code blocks as well the #' prefix. A good example for the documentation is mkdoc::mkdoc own manual page.

LINKS

Author: Detlef Groth
Homepage: https://github.com/mittelmark/DGTcl
Documentation of terminal application: https://core.tcl-lang.org/tcllib/doc/trunk/embedded/md/tcllib/files/apps/mkdoc.md
Documentation of library: https://core.tcl-lang.org/tcllib/doc/trunk/embedded/md/tcllib/files/modules/mkdoc/mkdoc.md
Version: 0.7.0
License: BSD

DETAILS

After installing Tcllib version 1.21 you should have the mkdoc application in your PATH. If you do not like to install Tcllib - which is recommended however, you can as well download the standalone Tcl script https://github.com/mittelmark/DGTcl/raw/master/bin/mkdoc-0.6.bin , rename it to mkdoc, make it executable and move this file to a folder belonging to your PATH variable. In both cases, thereafter extract embedded documentation with the command line application on the terminal like this:

mkdoc inputfile outputfile

For example to extract mkdoc's own documentation you could use:

mkdoc mkdoc.tcl mkdoc.html

Or if you would like to have pdf output and if you have pandoc installed:

mkdoc mkdoc.tcl mkdoc.md --pandoc
pandoc mkdoc.md -o mkdoc.pdf

If you do this pdf conversion, you might add before the pandoc conversion the YAML header again as this header is not Markdown syntax and might not display correctly in Markdown viewers.

Standalone executable

There is as well a standalone executable of the package, links see above, which contains attached to the file the required packages from tcllib. To install this executable just move it to your personal bin folder or other folders which are in your path, for example:

mv mkdoc-0.6.bin ~/bin/mkdoc
chmod 755 ~/bin/mkdoc

More explanations are here: https://github.com/mittelmark/DGTcl/tree/master/bin

CHANGES

2019-11-19: 0.1 initial version
2019-11-28: 0.2 direct conversion of markdown into html, starkit version, docu fixes
2020-02-26: 0.3 -css option for custom stylesheets, standalone application now with embedded Markdown package
2020-11-10: 0.4 --run command line option to execute the code in the EXAMPLE section
2022-02-11: 0.6.0 improved YAML support, better default css, terminal usage message improved, building standalone executable now with tpack
2022-05-07: 0.7.0 Now is part of Tcllib

SEE ALSO

Source Documentation Tools
Ruff! - similar purpose tool but using nicely Tcl introspection facilities, so focused on Tcl
pandoc-tcl-filter - contains now embedded mkdoc functionality
tmdoc::tmdoc for doing the reverse embedding Tcl code in Markdown documents for literate programming

DISCUSSION

Please discuss here.

DDG 2020-02-26: mkdoc is in its use similar to Ruff! which can also use Markdown for documentation. Whereas Ruff! uses further Tcl's nice introspection facilities, mkdoc requires to write the documentation without this help. That's might be a disadvantage, but at the same time mkdoc can be used not only to write documentation for Tcl, but as well for Perl, Python, C, C++ etc as long as you can embed the "#'" comment characters.

So to document a procedure using Ruff! you write:

proc character_at {text {pos 0}} {
     # Get the character from a string.
     #  text - Text string.
     #  pos  - Character position. 
     # The command will treat negative values of $pos as offset from
     # the end of the string.
     #
     # Returns the character at index $pos in string $text.
     ...
}

In contrast you write using mkdoc (stars are just for **bold** and *italic*), the greater sign is for indenting lines after the procedure name:

#' **character_at** *text ?pos 0?*
proc character_at {text {pos 0}} {
     #'
     #' > Get the character from a string.
     #'
     #' > - *text* - Text string.
     #'   - *pos*  - Character position, default: 0. 
     #'
     #' > The command will treat negative values of $pos as offset from
     #' the end of the string.
     #'
     #' > Returns the character at index $pos in string $text.
     ...
}

As said above, the mkdoc approach works as well for other programming languages.

DDG - 2020-11-10: Moved project to Github, updated to version 0.4 adding a --run argument to extract and execute the inline code in the example section.

DDG - 2022-02-11: Did some code clean up, building the standalone application now with tpack, improved help message in the terminal

APN - 2022-06-08: After updating to tcllib 1.21 I'm getting version conflicts on loading mkdoc. Which one is the official one - the tcllib one or the standalone package at github?

DDG - 2022-06-08: The release in tcllib should be the default one in the future. It is a slightly reduced version of the original mkdoc version (for instance no automatic ordering of function documentation anymore, no R-roxygen2 support). I will soon remove the github code to avoid such confusion. Sorry.

Category Documentation