Unverified Commit 33816440 authored by Jesse Mapel's avatar Jesse Mapel Committed by GitHub
Browse files

Contributor Documentatin Content Clean up (#4865) 



* More dev docs clean up

* finishing contributor Learn More page

* final contributor docs

Co-authored-by: default avatarladoramkershner <ladoramkershner@gmail.com>
parent eb5eb4cd

isis/cmake/BuildDocs.cmake

+9 −4
Original line number Diff line number Diff line
@@ -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()
@@ -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)

isis/src/docsys/build/DevExplore.xsl

+45 −100
Original line number Diff line number Diff line
@@ -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">
@@ -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 -->

<!-- Policies -->

      <hr/>

    <h2>Testing Guides</h2>

      <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>

          </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.

          </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="../Documents/CodingStandards/CodingStandards.html">

            Coding Standards and Style Guide</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.

          The coding standard and style guide for contributions to the ISIS code base.

          </td>

        </tr>

        <tr valign="top">

          <th style="width:25%">

            <a href="../documents/HowToApplicationCategoryTest/index.html">

            Legacy Makefile Tests Guide</a>

            <a href="https://github.com/USGS-Astrogeology/ISIS3/blob/dev/CONTRIBUTING.md">

            Contributing Guidelines</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>
@@ -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">
@@ -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>

isis/src/docsys/build/DevInspire.xsl

+29 −19
Original line number Diff line number Diff line
@@ -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>
@@ -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>
@@ -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 -->

isis/src/docsys/build/DevLearn.xsl

0 → 100644
+255 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet version="1.0"

    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

    xmlns:fo="http://www.w3.org/1999/XSL/Format"

    exclude-result-prefixes="xmlns fo">



<!--



This stylesheet will be used to generate the main TOC for the "User Docs" page



Author

Deborah Lee Soltesz

12/05/2002



-->





  <xsl:output

    media-type="text/html"

    doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"

    doctype-system="http://www.w3.org/TR/html4/loose.dtd"

    indent="yes"

    encoding="utf-8"

    omit-xml-declaration="yes"/>



  <xsl:include href="menu.xsl"/>





  <xsl:key name="categoryMatch" match="/tableofcontents/document" use="category/categoryItem"/>

  <xsl:key name="audienceMatch" match="/tableofcontents/document" use="audience/target"/>





  <xsl:template match="/">

     <xsl:apply-templates select="tableofcontents" />

  </xsl:template>





  <xsl:template match="tableofcontents">

    <html>

      <head>

        <title>

            USGS Isis: Getting Started Contributor Documentation

        </title>

        <meta name="keywords" content="about, overview, introduction, Isis, image processing, contributor, software, open source, remote sensing, planetary science, astrogeology"/>

        <meta name="description" content="About the Integrated Software for Imagers and Spectrometers (ISIS), created and managed by the USGS Astrogeology Research Program. ISIS provides a comprehensive, user-friendly, portable tool for processing, analyzing, and displaying remotely sensed image data."/>

        <meta name="publisher" content="USGS - GD - Astrogeology Program"/>

        <meta name="author" content="Deborah Lee Soltesz, webteam@astrogeology.usgs.gov"/>

        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

        <meta name="country" content="USA"/>

        <meta name="state" content="AZ"/>

        <meta name="county" content="Coconino"/>

        <meta name="city" content="Flagstaff"/>

        <meta name="zip" content="86001"/>



        <link rel="stylesheet" href="../assets/styles/IsisStyleCommon.css"/>

        <link rel="stylesheet" href="../assets/styles/main.css"/>

        <link rel="stylesheet" href="../assets/styles/menu.css"/>

        <link rel="stylesheet" media="print" href="../assets/styles/print.css"/>

        <!-- Dynamic analytics insertion to prevent running on local URLs -->

        <xsl:text>&#xa;</xsl:text>

        <script type="text/javascript">

          //<xsl:comment><![CDATA[

          (function() {

            var usgsAnalytics = document.createElement('script');

            usgsAnalytics.type = 'text/javascript';

            usgsAnalytics.async = true;

            usgsAnalytics.src = 'http://www.usgs.gov/scripts/analytics/usgs-analytics.js';

            if('http:' == document.location.protocol) {

              var s = document.getElementsByTagName('script')[0];

              s.parentNode.insertBefore(usgsAnalytics, s);

            }

          })();

          ]]></xsl:comment>

        <xsl:text>&#xa;</xsl:text>

        </script>

      </head>



      <body>



        <div class="isisMenu">

         <xsl:call-template  name="writeMenu"/>

        </div>



        <div class="isisContent">



        <a href="http://www.usgs.gov">

        <img src="../assets/icons/littleVIS.gif" width="80" height="22" border="0" alt="USGS"/></a><br/>





        <p style="margin-top:10px; padding-bottom:0px;">

        ISIS Documentation</p>



        <hr/>





        <table width="100%" cellpadding="0" border="0" cellspacing="0">

          <tr valign="top">

            <td align="left">

              <h1>

                Learn More About Contributing Code

              </h1>

              <p>

                ISIS is a large package with many places to contribute and

                improve the code base; however, the size and history of ISIS can

                be intimidating.

                On this page you will find resources to learn more about ISIS development

                and help with your first code contribution.

              </p>

              <p>

              </p>

            </td>

            <td align="right" class="caption">

            <a href="../index.html">Home</a>

            </td>

          </tr>

        </table>



<!-- Exercises -->

    <hr/>

    <h2>Programming Exercises</h2>

      <p>

        These self-guided exercises will have you explore the ISIS code base and

        learn about the ISIS API.

      </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 ISIS Programming</a>

          </th>

          <td>

          An exercise introduces you to the ISIS API by

          examining and altering an existing ISIS application.

          </td>

        </tr>

        <tr valign="top">

          <th style="width:25%">

            <a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Exercises_2">

            Advanced ISIS Programming</a>

          </th>

          <td>

          An exercise grows your understanding of the ISIS API by

          building on and refining the work you did in the previous exercise.

          </td>

        </tr>

      </table>





<!-- Contributing Guides -->

    <hr/>

    <h2>Contributing Guides</h2>

      <p>

        The previous exercises showed you how to write code in ISIS.

        These guides will show you how to contribute your code change back into

        the ISIS code base.

      </p>

      <table class="tableTOC">



        <!-- hardcoded links -->

        <tr valign="top">

          <th style="width:25%">

            <a href="">

            Adding a New Feature</a>

          </th>

          <td>

          A guide to the requirements when adding a new feature to ISIS.

          </td>

        </tr>

        <tr valign="top">

          <th style="width:25%">

            <a href="">

            Modifying an Existing Feature</a>

          </th>

          <td>

          A guide to the requirements when modifying an existing feature in ISIS.

          </td>

        </tr>

      </table>





<!-- Testing Guides -->

    <hr/>

    <h2>Testing Guides</h2>

      <p>

        Testing is a crucial component of creating sustainable software and a requirement for all

        code contributions to ISIS.

      </p>

      <p>

        As of version 3.6, ISIS uses googletest and CTest for new tests. A majority of existing tests 

        have been converted to this new framework, however, some tests are still using the legacy Makefile framework.

      </p>

      <p>

        These guides will help you create, run, and modify ISIS tests within both frameworks.

      </p>

      <h3>googletest and CTest</h3>

        <p>

          Contributors are required to use the googletest system for new tests and convert legacy Makefile tests wherever

          possible.

        </p>

      <table class="tableTOC">

        <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 googletest and CTest</a>

          </th>

          <td>

          A how-to guide for writing new tests and converting ISIS applications to the new callable format required

          by the googletest framework.

          </td>

        </tr>

      </table>



      <h3>Makefile</h3>

        <p>

          There are rare situations where existing legacy Makefile tests have not yet been converted and need to be updated. 

          These legacy Makefile tests use an input and truth data to confirm applications produce the proper output

          under the testing conditions. The following guides describe how to work within the legacy testing system

          and with the legacy testing data.

        </p>

      <table class="tableTOC">

        <tr valign="top">

          <th style="width:25%">

            <a href="../documents/HowToApplicationCategoryTest/index.html">

            Legacy Makefile Tests Guide</a>

          </th>

          <td>

          This document describes how legacy Makefile tests work.

          </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>

          </th>

          <td>

          This page explains how to download the test input/truth data required to run the legacy ISIS test suite.

          </td>

        </tr>

      </table>





<!-- FOOTER -->

<script type="text/javascript" language="JavaScript" src="../assets/scripts/footer.js"></script>

</div>





      </body>

    </html>



  </xsl:template>





</xsl:stylesheet>

isis/src/docsys/build/DevStart.xsl

+52 −71

File changed.

Preview size limit exceeded, changes collapsed.