The MUSIM Documentation Process

twm - 12/16/09

Introduction

The documentation of MUSIM evolved over time as was needed at that time.   The early attemps were characterized by the use of a text editor and conversion to PDF files for distribution.   The most current version was developed using custom written html files to give structure to the documentation that was then generated by Doxygen .   This README describes that process.

1 - The Overall Structure

Several html files were written to give structure to the documentation.   Those files are also used to document the MUSIM features that Doxygen was not designed for, such as the history, and the installation, the hardware architecture etc.   Those files are named as follows:

main.html
history.html
architecture.html
install.html
authors.html
faq.html
hierarchy.html
readme.html
search.html

All of the above files were hand coded using gedit . The remainder of the documentation pages were created using Doxygen , a source code documentation generation tool.

2 - The Doxygen Approach

Doxygen was used to document the MUSIM code using two different techniques.   The first way was simply to run Doxygen on ~/projects/MUSIM/src.   This gives documentation for the entire MUSIM, without any consideration to the individual processes ( of which there are typically seven or more ).   The second technique breaks the MUSIM documentation into it's component processes, and documented each as an individual entity. &nbsdp; The different Doxygen techniques were made using simple modifications to the Doxygen input parameter file DoxyFile.   The Doxygen docs are created by entering "doygen" in a command shell.   The parameter file 'DoxyFile' must reside in the directory from where 'doxygen' is entered.   The parameter file 'doxygen' tells Doxygen where to start the source code evaluation and where to put the output (among many other options).

3 - Integrating Doxygen Produced files with the hand coded html files

Doxygen creates many files, depending on what is requested of it. The root html file for any body of documentation (which could be a process, a library or the entire MUSIM) is named 'index.html'. For the MUSIM documentation, I integrated the Doxygen docs with the hand coded HTML by changing a few lines in that 'index.html' file. A shell script was created to automate the documentation building process.

1) As a regular user (not root) go to ~/projects/MUSIM/doxyDocs

2) type 'MakeDocs' at the command line.

3) The new documentation is now complete.

Type

firefox main.html

to view the documentation.

V1.0