Examples

We present below some examples of (artificial and actual) use of the script (whose usage is described here), and also provide with all related help for the implementation.

Shared documentation of multiple languages

In the examples/) folder, various dummy programs implemented in different programming languages are provided so as to illustrate the use of the common template, e.g. SAS, R, Python, etc… functions and scripts under the idir1/ and idir2/ directories are documented. The script src2mddoc.sh can be run to automatically extract the documentation from any of those files, e.g. the command:

bash src2mddoc.sh -v -p -d examples/odir/md/process2/
	examples/idir1/_example_function.R

will extract the header documentation from the source file _example_function.R in examples/idir1/ and store it as a new markdown file named r__example_function.md in the examples/odir/md/process2/ directory. The ex_src2mddoc.sh script will enable you to extract the header documentations from all available source files at once, e.g. run:

bash examples/ex_src2mddoc.sh

so the output markdown files (one for each program) will be created in the (arbitrarily selected) directories process1/ and process2/ in examples/odir/md/. Note also the presence of the _static_/ directory in examples/odir/md/ folder: it contains static/ready-made markdown files that will actually define the structure/organisation of the final browsable documentation. They can be adapted/modified by the user; more can be added.

Further, the document generator Doxygen is used to generate the html browsable documentation, e.g. run:

bash examples/ex_mddoc2html.sh

since it essentially launches:

doxygen examples/dox/doxygen-dumb-config.cfg

where the configuration file doxygen-dumb-config.cfg provides with different settings for the output html documents (see the configuration page of Doxygen documentation). The final html browsable documentation is created under the folder examples/odir/html and can be launched from the index.html page. A preview is available in this page, however you will not be able to browse the whole documentation from there.

Shared documentation of various programming languages: in this example, the documentation of different stand-alone programs (implemented in SAS, R, Python, Matlab, etc...) is made available (and browsable) from a common (single-entry) webpage.

PING software documentation

The documentation of PING software has been generated automatically using this approach. It can be found here.

The markdown files are again generated using the src2mddoc.sh script, e.g. run:

bash src2mddoc.sh -v -p -d PING/docs/md/library/ 
	PING/library/pgm/*

so as to extract the documentation headers from all source files (whatever format) present in the input directory library/pgm and store the generated markdown files into the output directory docs/md/library (no suffix, programming language added as prefix).

Following, the script ping2html.sh script is used (and further adapted) so as to generate automatically the final browsable html documentation, running the Doxygen inline command as follows:

doxygen doxygen-ping-config.cfg

with the doxygen-formatted configuration file doxygen-ping-config.cfg.

Statistical operations are documented regardless of the programming languages: in this example, the documentation of a quantile estimation is provided for both SAS and R implementations.