Skip to content

Commit

Permalink
Contributor Documentatin Content Clean up (DOI-USGS#4865)
Browse files Browse the repository at this point in the history 
* More dev docs clean up

* finishing contributor Learn More page

* final contributor docs

Co-authored-by: ladoramkershner <ladoramkershner@gmail.com>
  • Loading branch information
@jessemapel @ladoramkershner
jessemapel and ladoramkershner committed Apr 14, 2022
1 parent 8107a71 commit e26d522
Show file tree
Hide file tree
Showing 8 changed files with 423 additions and 208 deletions.
13 changes: 9 additions & 4 deletions isis/cmake/BuildDocs.cmake
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,9 @@ endfunction(copy_app_docs_info)
function(build_upper_level)

# Make new (empty) output folders
set(newFolders UserDocs UserStart UserLearn UserExplore UserInspire DevStart DevExplore DevInspire General Guides Installation TechnicalInfo)
set(newFolders UserStart UserLearn UserExplore UserInspire
DevStart DevLearn DevExplore DevInspire
UserDocs General Guides Installation TechnicalInfo)
foreach(f ${newFolders})
file(MAKE_DIRECTORY "${docInstallFolder}/${docVersion}/${f}")
endforeach()
Expand Down Expand Up @@ -202,13 +204,16 @@ function(build_documents_folder)
# USER GET INSPIRED DOCS TOC
execute_process(COMMAND ${XALAN} ${XALAN_PARAM_OPTION} menuPath \"../\" ${XALAN_OUTFILE_OPTION} ${docInstallFolder}/${docVersion}/UserInspire/index.html ${XALAN_INFILE_OPTION} ${doctocPath} ${XALAN_XSL_OPTION} ${docBuildFolder}/build/UserInspire.xsl)

# USER GET INSPIRED DOCS TOC
# DEV GETTING STARTED DOCS TOC
execute_process(COMMAND ${XALAN} ${XALAN_PARAM_OPTION} menuPath \"../\" ${XALAN_OUTFILE_OPTION} ${docInstallFolder}/${docVersion}/DevStart/index.html ${XALAN_INFILE_OPTION} ${doctocPath} ${XALAN_XSL_OPTION} ${docBuildFolder}/build/DevStart.xsl)

# USER GET INSPIRED DOCS TOC
# DEV LEARN MORE DOCS TOC
execute_process(COMMAND ${XALAN} ${XALAN_PARAM_OPTION} menuPath \"../\" ${XALAN_OUTFILE_OPTION} ${docInstallFolder}/${docVersion}/DevLearn/index.html ${XALAN_INFILE_OPTION} ${doctocPath} ${XALAN_XSL_OPTION} ${docBuildFolder}/build/DevLearn.xsl)

# DEV EXPLORE IN DETAIL DOCS TOC
execute_process(COMMAND ${XALAN} ${XALAN_PARAM_OPTION} menuPath \"../\" ${XALAN_OUTFILE_OPTION} ${docInstallFolder}/${docVersion}/DevExplore/index.html ${XALAN_INFILE_OPTION} ${doctocPath} ${XALAN_XSL_OPTION} ${docBuildFolder}/build/DevExplore.xsl)

# USER GET INSPIRED DOCS TOC
# DEV GET INSPIRED DOCS TOC
execute_process(COMMAND ${XALAN} ${XALAN_PARAM_OPTION} menuPath \"../\" ${XALAN_OUTFILE_OPTION} ${docInstallFolder}/${docVersion}/DevInspire/index.html ${XALAN_INFILE_OPTION} ${doctocPath} ${XALAN_XSL_OPTION} ${docBuildFolder}/build/DevInspire.xsl)

endfunction(build_documents_folder)
Expand Down
145 changes: 45 additions & 100 deletions isis/src/docsys/build/DevExplore.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,18 +97,12 @@ Deborah Lee Soltesz
<tr valign="top">
<td align="left">
<h1>
Contributor Explore in Detail
Explore the Details of Contributing Code
</h1>
<p>
Creating and maintaining quality tools is not simple. ISIS contributors have
worked hard to create accurate references and guides to support future
contributions. If you encounter a specific case that could help future
contributors, feel free to submit documentation for this page.
</p>
<p>
On this page you will find detailed references and specialized guides for contributing to ISIS.
</p>
<p>
This page contains references, policies, and highly specific guides for contributing code
to ISIS. These are working resources to help you as you develop your code and go through
the contribution process.
</p>
</td>
<td align="right" class="caption">
Expand All @@ -118,90 +112,87 @@ Deborah Lee Soltesz
</table>


<!-- Documentation Guides​ -->
<!-- API Reference​ -->
<hr/>
<h2>Documentation Guides</h2>
<h2>API Reference</h2>
<p>
If you're not familiar with working on the ISIS documentation,
these guides can help get you started.
Here you will find the documentation for the ISIS library API.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Contributing-Application-Documentation">
Contributing ISIS Application Documentation</a>
<a href="../Object/Developer/index.html">
ISIS Library API reference</a>
</th>
<td>
This how-to guide will take you through the steps required to write and modify the ISIS
application documentation.
Documentation for all of the classes, functions, and variables in the ISIS library.
</td>
</tr>
</table>


<!-- XML Schemas -->
<hr/>
<h2>XML Schemas</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.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="../documents/HowToApplicationExamples/index.html">
ISIS Application Examples Guide</a>
<a href="../Schemas/Application/documentation/index.html">
ISIS Application XML Schema</a>
</th>
<td>
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.
The schema that 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="../documents/HowToGeneralDocumentation/index.html">
General ISIS Documentation Guide</a>
<a href="../Schemas/Documentation/documentation/index.html">
ISIS Web Documentation XML Schema</a>
</th>
<td>
This how-to guide covers writing documentation for this website.
The schema that 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>


<!-- Testing Guides -->
<hr/>
<h2>Testing Guides</h2>
<!-- Policies -->
<hr/>
<h2>Policies</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.
As open-source software, it is important to define how the community is expected to interact.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Writing-ISIS3-Tests-Using-Gtest-and-Ctest">
Writing Tests Using GTest and CTest</a>
<a href="../Documents/CodingStandards/CodingStandards.html">
Coding Standards and Style Guide</a>
</th>
<td>
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.
The coding standard and style guide for contributions to the ISIS code base.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Test-Data-Obtaining,-Maintaining,-and-Submitting">
ISIS Test Data</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/blob/dev/CONTRIBUTING.md">
Contributing Guidelines</a>
</th>
<td>
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="../documents/HowToApplicationCategoryTest/index.html">
Legacy Makefile Tests Guide</a>
</th>
<td>
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.
Guidelines for contributors and reviewers during the contribution process.
</td>
</tr>
</table>
Expand All @@ -212,7 +203,7 @@ Deborah Lee Soltesz
<h2>Maintainer Guides</h2>
<p>
These resources are useful for maintainers and outline the processes that
support the broader user and contributor community.
support the broader community.
</p>
<table class="tableTOC">

Expand All @@ -223,53 +214,7 @@ Deborah Lee Soltesz
Release Process</a>
</th>
<td>
This guide goes through all the steps required to create both release candidates
and full releases.
</td>
</tr>
</table>


<!-- API Reference​ -->
<hr/>
<h2>ISIS API Reference</h2>
<p>
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>


<!-- XML Schemas -->
<hr/>
<h2>XML Schemas</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.
</p>
<table class="tableTOC">

<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="../Schemas/Application/documentation/index.html">
ISIS Application XML Schema</a>
</th>
<td>
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="../Schemas/Documentation/documentation/index.html">
ISIS Web Documentation XML Schema</a>
</th>
<td>
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.
The guide that describes the steps required to create both release candidates and full releases.
</td>
</tr>
</table>
Expand Down
48 changes: 29 additions & 19 deletions isis/src/docsys/build/DevInspire.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,15 +97,12 @@ Deborah Lee Soltesz
<tr valign="top">
<td align="left">
<h1>
Contributor Get Inspired
Get Inspired to Contribute
</h1>
<p>
Now that you've got all the resources you need to contribute,
you may be asking "what should I contribute?"
</p>
<p>
On this page you will find resources that will inspire you and give you
some ideas about what other users are interested in too.
ISIS is always under improvement and contributions are continuously coming in from the community.
If you want to contribute too but are unsure of where to start, here are some resources
that may inspire you and show you what other users are interested in.
</p>
<p>
</p>
Expand All @@ -129,22 +126,22 @@ Deborah Lee Soltesz
<!-- hardcoded links -->
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement">
Enhancement Requests</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>
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.
Issues labeled with Good First Issue have been idenditifed by other contributors as
places where newcomers can get started.
</td>
</tr>
<tr valign="top">
<th style="width:25%">
<a href="https://github.com/USGS-Astrogeology/ISIS3/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22">
Good First Issues</a>
<a href="https://github.com/USGS-Astrogeology/ISIS3/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement">
Enhancement Requests</a>
</th>
<td>
Issues labeled with Good First Issue have been idenditifed by other contributors as
places where newcomers can get started.
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>
</table>
Expand All @@ -154,11 +151,24 @@ Deborah Lee Soltesz
<hr/>
<h2>GitHub Pull Requests</h2>
<p>
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.
Pull requests represent what is currently being worked on in ISIS and are
a great place to interact with active contributors.
Even if you cannot review a pull request; comments, questions, 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/pulls">
Open pull requests</a>
</th>
<td>
Look at the open pull requests and see if there are any that interest you.
</td>
</tr>
</table>


<!-- FOOTER -->
Expand Down
Loading

0 comments on commit e26d522

Please sign in to comment.