Software Documentation
SCEC software engineering group distributes numerous scientific software codes to the research community. These software codes are accompanied by documentation to explain how to use these codes effectively.
Contents
Overview
CME Project software developers integrate complex scientific codes together into larger computational systems that we call Computational Platforms. These computational platform provide valuable research tools to the scientific community. To ensure these end user can make full use of the platforms capabilities, necessary software documentation is provided with these platforms. The two key forms of documentation SCEC strives to provide are detailed 'User Guides' and web-based, project 'Wiki' pages.
Types of Documentation
Wiki Pages
Web-based documentation, Project Wiki pages, are hosted on SCECPedia, a collaborative wiki site for SCEC's Community Modeling Environment (CME). Wiki pages on SCECPedia are constantly updated and reflect the most current information on Scientific Projects and related code that is distributed by SCEC.
Project Wiki pages include:
- Description of the project.
- List of supporting materials:
- Data formats.
- Software platform requirements.
- Links to code download sites.
- Links to software defect reporting and tracking website.
- List of references.
Users are encouraged to explore SCECPedia to get a broad understanding of specific scientific project and any related projects or codes.
User Guides
Detailed, version specific software documentation in the form of a User Guide is provided with each of scientific software platforms distributed by SCEC. User guides contain information required by the end user to install and use the software with ease. An online copy of this guide is maintained on the SCECPedia site.
User guides include:
- Information on how to download the software.
- Software requirements for running the scientific code:
- Operating System and version.
- Required compilers
- Required supporting software tools and packages.
- Building the scientific code.
- Testing the built code.
- Running the built code.
- Various examples to illustrates available features.
- Software support contact information.
- Optional troubleshooting information.
Online/Offline Documentation
In order to maintain consistency between the online User Guides and PDF based documents distributed with the scientific codes, SCEC developers use automated scripts which use HTMLDOC to transcribe the Wiki based User Guide to the PDF document.
To convert the Wiki User Guide to a PDF document the automated script:
- Downloads the Wiki User Guide HTML code with "wget"
- Changes the character encoding in the HTML file
- Removes the Wiki site related HTML from header and footer of web page and insert custom HTML.
- Run htmldoc to produce the PDF in "book" format.
A sample conversion script is available at [/home/scec-00/patrices/utils/htmldoc-1.8.27-aftershock]. HTMLDOC can be obtained from the HTMLDOC project page.
