Skip to content

Commit

Permalink
Updated user documentation content (DOI-USGS#4856)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jessemapel
jessemapel committed Apr 14, 2022
1 parent 18140f1 commit 8107a71
Show file tree
Hide file tree
Showing 11 changed files with 229 additions and 327 deletions.
172 changes: 64 additions & 108 deletions isis/src/docsys/build/DevExplore.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,202 +118,158 @@ Deborah Lee Soltesz
</table>


<!-- API Reference​ -->
<!-- Documentation Guides​ -->
<hr/>
<h2>ISIS API Reference</h2>
<h2>Documentation Guides</h2>
<p>
The ISIS API reference is particularly useful if you are working on an application
or interested in using the ISIS library as a dependency.
If you're not familiar with working on the ISIS documentation,
these guides can help get you started.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://astrodiscuss.usgs.gov/">
astrodiscuss</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Contributing-Application-Documentation">
Contributing ISIS Application Documentation</a>
</th>
<td>
Ask or answer questions on out community discussion board.
This how-to guide will take you through the steps required to write and modify the ISIS
application documentation.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/issues">
GitHub Issues</a>
<a href="../documents/HowToApplicationExamples/index.html">
ISIS Application Examples Guide</a>
</th>
<td>
Comment on bug reports or feature requests from other users.
This how-to guide covers writing examples for ISIS application documentation.
Application examples are a specialized section of the ISIS application
documentation and require additional steps besides editing the application XML.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/discussions?discussions_q=label%3ARFC">
Requests for Comment</a>
<a href="../documents/HowToGeneralDocumentation/index.html">
General ISIS Documentation Guide</a>
</th>
<td>
Provide feedback on major changes proposed for ISIS.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS_TC">
ISIS Technical Committee</a>
</th>
<td>
Get involved in project governance.
This how-to guide covers writing documentation for this website.
</td>
</tr>
</table>


<!-- XML Schemas -->
<hr/>
<h2>XML Schemas</h2>
<!-- Testing Guides -->
<hr/>
<h2>Testing Guides</h2>
<p>
The interface for ISIS applications and much of the ISIS documentation (including this
very page) are generated from XML files. These schemas are a helpful reference if you
are creating a new application, modifying application arguments, or writing documentation.
Testing is a crucial component of creating sustainable software and a requirement for all
code contributions to ISIS. These guides will help you run and modify the ISIS test suite.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#getting-started-with-github">
Downloading the Source Code</a>
</th>
<td>
How to pull the source code from GitHub.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#anaconda-and-isis3-dependencies">
Dependency Management</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Writing-ISIS3-Tests-Using-Gtest-and-Ctest">
Writing Tests Using GTest and CTest</a>
</th>
<td>
How to download the dependencies required to build ISIS.
As of version 3.6, ISIS uses googletest and CTest for testing. This how-to guide will
walk you through the steps required to write tests using the new frameworks. It also
covers the steps needed to convert ISIS applications to the new callable format.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#building-isis3">
Building</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Test-Data-Obtaining,-Maintaining,-and-Submitting">
ISIS Test Data</a>
</th>
<td>
How to build ISIS once you have the source code and dependencies downloaded.
Legacy Makefile based tests in ISIS use a input and truth data to confirm that the
aplications produce the proper output. This page explains how to download these
files required to run the ISIS test suite.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#running-tests">
Running the Test Suite</a>
<a href="../documents/HowToApplicationCategoryTest/index.html">
Legacy Makefile Tests Guide</a>
</th>
<td>
How to run the ISIS test suite once ISIS is built.
This documents describes how legacy Makefile tests work. Contributors are required
to use the new googletest system for new tests, but there are rare situations where
existing legacy Makefile tests need to be updated and cannot be converted.
</td>
</tr>
</table>


<!-- Documentation Guides​ -->
<!-- Maintainer Guides​ -->
<hr/>
<h2>Documentation Guides</h2>
<h2>Maintainer Guides</h2>
<p>
If you're not familiar with working on the ISIS documentation,
these guides can help get you started.
These resources are useful for maintainers and outline the processes that
support the broader user and contributor community.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Exercises_1">
Basic ISIS3 Programming</a>
</th>
<td>
hese exercises will walk you through the basics of ISIS applications.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Exercises_2">
Advanced ISIS Programming Exercises</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Public-Release-Process">
Release Process</a>
</th>
<td>
These exercises give you the chance to explore more yourself and interact with more
complex components of the ISIS API.
This guide goes through all the steps required to create both release candidates
and full releases.
</td>
</tr>
</table>


<!-- Testing Guides -->
<!-- API Reference​ -->
<hr/>
<h2>Testing Guides</h2>
<h2>ISIS API Reference</h2>
<p>
Testing is a crucial component of creating sustainable software and a requirement for all
code contributions to ISIS. These guides will help you run and modify the ISIS test suite.
The <a href="../Object/Developer/index.html">ISIS API reference</a> is particularly
useful if you are working on an application or interested in using the ISIS library
as a dependency.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="">
Adding a New Feature</a>
</th>
<td>
This document will walk you through what's needed when adding a new feature to ISIS.
If there is something you think is missing in ISIS this will walk you through the
steps needed to add it.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="">
Modifying an Existing Feature</a>
</th>
<td>
Modifying an existing feature is slightly more complex than adding a new feature to ISIS.
This document will walk you through what is different when you are building from an
existing feature instead of something new.
</td>
</tr>
</table>


<!-- Maintainer Guides​ -->
<hr/>
<h2>Maintainer Guides</h2>
<!-- XML Schemas -->
<hr/>
<h2>XML Schemas</h2>
<p>
These resources are useful for maintainers and outline the processes that
support the broader user and contributor community.
The interface for ISIS applications and much of the ISIS documentation (including this
very page) are generated from XML files. These schemas are a helpful reference if you
are creating a new application, modifying application arguments, or writing documentation.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="">
Adding a New Feature</a>
<a href="../Schemas/Application/documentation/index.html">
ISIS Application XML Schema</a>
</th>
<td>
This document will walk you through what's needed when adding a new feature to ISIS.
If there is something you think is missing in ISIS this will walk you through the
steps needed to add it.
This schema defines the ISIS application XML format. This includes the applications
documentation and all of the application arguments.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="">
Modifying an Existing Feature</a>
<a href="../Schemas/Documentation/documentation/index.html">
ISIS Web Documentation XML Schema</a>
</th>
<td>
Modifying an existing feature is slightly more complex than adding a new feature to ISIS.
This document will walk you through what is different when you are building from an
existing feature instead of something new.
This schema defines the XML documentation format used to generate this documentation.
If you want to make a change to the ISIS website documentation, then you will need to
reference this schema for your changes.
</td>
</tr>
</table>
Expand Down
84 changes: 13 additions & 71 deletions isis/src/docsys/build/DevInspire.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,49 +121,30 @@ Deborah Lee Soltesz
<hr/>
<h2>GitHub Issues</h2>
<p>
The first step for all code contributions to ISIS is a GitHub issue. Look at the open
enhancement requests to see what other members of the community have asked for and maybe
there will be something you are interested in too. It you just want to get started with
contributing code; issues labeled with Good First Issue are an excellent place for
newcomers to start.
The first step for all code contributions to ISIS is a GitHub issue. If you want to get started with
contributing code, then start with the currently open issues.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://astrodiscuss.usgs.gov/">
astrodiscuss</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement">
Enhancement Requests</a>
</th>
<td>
Ask or answer questions on out community discussion board.
Look at the open enhancement requests to see what other members of the community have
asked for and maybe there will be something you are interested in too.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/issues">
GitHub Issues</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22">
Good First Issues</a>
</th>
<td>
Comment on bug reports or feature requests from other users.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/discussions?discussions_q=label%3ARFC">
Requests for Comment</a>
</th>
<td>
Provide feedback on major changes proposed for ISIS.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS_TC">
ISIS Technical Committee</a>
</th>
<td>
Get involved in project governance.
Issues labeled with Good First Issue have been idenditifed by other contributors as
places where newcomers can get started.
</td>
</tr>
</table>
Expand All @@ -173,50 +154,11 @@ Deborah Lee Soltesz
<hr/>
<h2>GitHub Pull Requests</h2>
<p>
If you are interested in what other contributors are working on, look at the GitHub
pull requests that are currently open. Even if you do not have write permissions to the
If you are interested in what other contributors are working on, look at the
<a href="https://github.com/USGS-Astrogeology/ISIS3/pulls">GitHub pull requests</a>
that are currently open. Even if you do not have write permissions to the
repository, input and testing on pull requests are always appreciated.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#getting-started-with-github">
Downloading the Source Code</a>
</th>
<td>
How to pull the source code from GitHub.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#anaconda-and-isis3-dependencies">
Dependency Management</a>
</th>
<td>
How to download the dependencies required to build ISIS.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#building-isis3">
Building</a>
</th>
<td>
How to build ISIS once you have the source code and dependencies downloaded.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#running-tests">
Running the Test Suite</a>
</th>
<td>
How to run the ISIS test suite once ISIS is built.
</td>
</tr>
</table>


<!-- FOOTER -->
Expand Down
Loading

0 comments on commit 8107a71

Please sign in to comment.