Documentation for new Kalpana app

[ashtonvcole]

Updated documentation to reflect the new Kalpana v0.0.24 application. Attention is given to the simpler web interface experience. Included links to source code and developer documentation.

[wesleyboar]

I've deployed this as is (via #210), to provide for users swiftly, but I suggest these changes (to simplify maintenance in this repo and improve usability).

Thoughts?

[wesleyboar]

1. New content uses Markdown syntax.
2. We can just link name of page to the URL.

Suggested change

	<ul>
	<li>The CCHT website: <a href="https://ccht.ccee.ncsu.edu/kalpana/" target="_blank">https://ccht.ccee.ncsu.edu/kalpana/</a></li>
	<li>The official GitHub repository, which contains the latest release and examples: <a href="https://github.com/ccht-ncsu/Kalpana" target="_blank">https://github.com/ccht-ncsu/Kalpana</a></li>
	</ul>
	- [Kaplana page on CCH website](https://ccht.ccee.ncsu.edu/kalpana/)
	- [official GitHub repository](https://github.com/ccht-ncsu/Kalpana), which contains the latest release and examples

[wesleyboar]

1. New content uses Markdown syntax.
2. Using back-ticks around API/code terms distinguish them as such.

Suggested change

	<ul>
	<li><b>ADCIRC File.</b> See the reference table below. Generic NetCDF files may also be accepted, if formatted appropriately.</li>
	<li><b>Variable.</b> Preceded by flag --var. The variable of interest from the NetCDF file. See the reference table below.</li>
	<li><b>Contour levels.</b> Preceded by flag --levels. Separated by spaces, the minimum contour, maximum contour, and step size.</li>
	<li><b>Vertical units out.</b> m or ft</li>
	<li><b>Vertical units in.</b> m or ft</li>
	<li><b>Time Steps.</b> Preceded by flag --timesteps. For time-varying files, specific time steps to extract are provided, separated by spaces. Otherwise, all are exported.</li>
	</ul>
	- **ADCIRC File.** See the reference table below. Generic NetCDF files may also be accepted, if formatted appropriately.
	- **Variable.** Preceded by flag `--var`. The variable of interest from the NetCDF file. See the reference table below.
	- **Contour levels.** Preceded by flag `--levels`. Separated by spaces, the minimum contour, maximum contour, and step size.
	- **Vertical units out.** m or ft
	- **Vertical units in.** m or ft
	- **Time Steps.** Preceded by flag `--timesteps`. For time-varying files, specific time steps to extract are provided, separated by spaces. Otherwise, all are exported.

[wesleyboar]

1. New content uses Markdown syntax.
2. We can just link name of content to the URL.
3. Consider linking directly to the function, so user need not search.
4. Consider linking to current version of code, so future refactors do not make user guide inaccurate.

Suggested change

	To generate shapefiles for an ensemble, or to modify advanced Kalpana settings, submit JSON job requests using TapiPy (<a href="https://github.com/tapis-project/tapipy" target="_blank">https://github.com/tapis-project/tapipy</a>). Descriptions for each flag are available in the Tapis app specification or the source file on GitHub, see function nc2shp (<a href="https://github.com/ccht-ncsu/Kalpana/blob/master/kalpana/export.py" target="_blank">https://github.com/ccht-ncsu/Kalpana/blob/master/kalpana/export.py</a>).
	To generate shapefiles for an ensemble, or to modify advanced Kalpana settings, submit JSON job requests using [TapiPy](https://github.com/tapis-project/tapipy){ target="_blank" }. Descriptions for each flag are available in the Tapis app specification or the source file on GitHub, see [function `nc2shp`](https://github.com/ccht-ncsu/Kalpana/blob/v0.0.25/kalpana/export.py#L764){ target="_blank" }).

[wesleyboar]

I make suggestions that can let user skim faster.

[wesleyboar]

1. Consider removing "regarding Kalpana", because user is reading doc for Kaplana, so the context seems obvious.
2. Consider removing "can be found at", because it does not seem to assist the reader. The phrase ends with a colon, so a complete sentence is not necessary.

Suggested change

	Kalpana is a Python library which primarily converts ADCIRC NetCDF output files to GIS-compatible shapefiles. Secondary functions are not available in the DesignSafe application. It was developed by the Coastal and Computational Hydraulics Team at North Carolina State University. More information regarding Kalpana can be found at:
	Kalpana is a Python library which primarily converts ADCIRC NetCDF output files to GIS-compatible shapefiles. Secondary functions are not available in the DesignSafe application. It was developed by the Coastal and Computational Hydraulics Team at North Carolina State University. More information:

[wesleyboar]

1. To streamline content digestion for user…

   • reduces verbosity
   • avoids "Required" being ignored (by a reader skimming) because it:
     • is within a sentence reader may skim over
     • may appear on the right side of the page¹

Suggested change

	Generating contours for a single case is simple through the web interface. The following information is required:
	Generating contours for a single case is simple through the web interface.
	Required Information:

Footnotes

1. Readers that skim may be scanning left side of page for headings, sentence starts, list introductions, et cetera. ↩

[wesleyboar]

Because I already merged this in (via #210), updating branch with main now would make all comment unable to be applied with one-click.

Consider how to proceed, e.g.

• Accept or decline suggestions via GitHub UI, then update branch and resolve possible merge conflicts.
• Update branch, then manually apply any approved suggestions.