Merge branch 'frontpage' into 'main'

# asc-public-docs

## Getting started

To make it easy for you to get started with GitLab, here's a list of recommended next steps.

### Cloning and Rendering the Docs Locally

Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!

```bash   

# 1. Clone the forked repository to your local machine:   

git clone git@code.usgs.gov:astrogeology/asc-public-docs.git

cd asc-public-docs/

## Add your files

# 2. Create a branch to track your work

git checkout -b your-branch-name 

- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files

- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:

# 3. install dependencies 

pip install -r requirements.txt

# 4. Make your changes to the code 

# ...

# 5. Preview your changes, in the root of the repo run

mkdocs serve

# 6. Push your changes to the branch

git push origin your-branch-name

```

cd existing_repo

git remote add origin https://code.usgs.gov/astrogeology/asc-public-docs.git

git branch -M main

git push -uf origin main

```

***

### Adding your files

1. Determine what category your docs belong to by reading [the summary on the README](#understanding-the-doc-system). 

2. Write your either in Markdown or as a Jupyter notebook and add it under the directory for that category. 

3. Update `mkdocs.yml`, add a new file somewhere appropriate under `nav:` 

4. Run `mkdocs serve` to check if your file(s) rendered correctly.

### Getting Your Changes Reviewed

## Description

1. On the merge requests tab of the repository in GitLab, you will see a "New merge request" button. Click on it.

1. Select your branch (feature/your-feature-branch) from the Source branch dropdown.

1. Specify the target branch (e.g., master) in the Target branch field.

1. Fill in the necessary information about your changes, including a descriptive title and a description of what your MR proposes.

1. Submit the merge request.

1. Assign reviewers if there isn't any traction for your MR by adding them as reviewers or pinging them in the MR.

1. Address any feedback or comments provided by the reviewers.

1. Once all the reviewers have approved your changes, one of the maintainers will merge your MR into the main branch.

1. The continuous deployment system should automatically deploy your new changes. 

1. Celebrate your contribution! :tada:

## Contributing Docs

## Understanding The Doc System

Contributors should consider writing new docs under one of our four categories:

1. Getting Started 

1. Getting Started Tutorials

1. How-To Guides 

1. Concepts 

1. Software Manuals

### Getting Started Docs

We use these four categories to cover the range of potential docs while clarifying to authors and readers for what kind of documentation goes where. 

|                 | Getting Started       | How-Tos                        | Concepts                   | Manuals                                               |

|-----------------|-----------------------|--------------------------------|----------------------------|-------------------------------------------------------|

| **Oriented To**     | Learning              | Achieving a Goal               | Understanding              | Referencing                                           |

| **Composed As**     | Step-by-Step Jupyter or Similar Tutorial | General Purpose Guide          | Written Summary            | Generated Sphinx/Doxygen Site                         |

| **Has the Goal of** | Enabling Beginners    | Showing How To Solve A Problem | Give Detailed Written Explanations | Give Dry Descriptions of Libraries, Services and Apps |

| **Example**  | Jupyter notebook with toy data on how to ingest and project images | A breakdown of quirks working with Themis Images  |   Write-up on how ISIS defines projections | ISIS library Doxygen reference |

This website structure borrows from the [Divio documentation system](https://documentation.divio.com/), except adapted to more specifically adhere to how our software is already structured, renamed the categories to be more specific, and have more focus on the composition (or mode of writing) of the docs to reduce ambiguity. One can't expect any categorical structure for software documentation to be orthogonal to eachother. There will always exist some degree of overlap between categories as the quantity of documentation grows. Documentation in one category can easily have overlapping information with those in others. However, composition of the doc (e.g., jupyter notebook with an explicit starting and end point, short how-to guide with code examples but ambigious starting point and end point, written explanation without code, doxygen API reference) is less ambigious that whether or not your docs can be considered a guide or a tutorial.    

### Getting Started Tutorials

These are longer "learn by doing" exercises that users can follow to learn some extended process using the libraries. These should have the user execute code or run commands from the library to complete a task.

# ISIS App Testing Cookbook 

### Main.cpp Templates 

#### Minimum 

This is generally used when no logs are printed and special help GUI functionality is needed.

```C++

#include "Isis.h"

#include "Application.h"

#include "app_func.h" # replace with your new header

using namespace Isis;

void IsisMain() {

  UserInterface &ui = Application::GetUserInterface();

  app_func(ui);

}

```

#### Application with Logs 

When the application expects to print PVL logs to standard output. Most common case. 

```C++

#include "Isis.h"

#include "Application.h"

#include "Pvl.h"

#include "app_func.h" # replace with your new header

using namespace Isis;

void IsisMain() {

  UserInterface &ui = Application::GetUserInterface();

  Pvl appLog;

  try {

    app_func(ui, &appLog);

  }

  catch (...) {

    for (auto grpIt = appLog.beginGroup(); grpIt!= appLog.endGroup(); grpIt++) {

      Application::Log(*grpIt);

    }

    throw;

  }

  for (auto grpIt = appLog.beginGroup(); grpIt!= appLog.endGroup(); grpIt++) {

    Application::Log(*grpIt);

  }

}

```

#### Application with GuiLogs 

Logs that are only to be printed to the GUI command line in interactive mode. 

```C++

#include "Isis.h"

#include "Application.h"

#include "SessionLog.h"

#include "app_func.h" # replace with your new header

using namespace Isis;

void IsisMain() {

  UserInterface &ui = Application::GetUserInterface();

  Pvl appLog;

  app_func(ui);

  // in this case, output data are in a "Results" group.

  PvlGroup results = appLog.findGroup("Results");

  if( ui.WasEntered("TO") && ui.IsInteractive() ) {

    Application::GuiLog(results);

  }

  SessionLog::TheLog().AddResults(results);

}

```

#### Application with GUIHELPERS

Some apps require a map with specialized GUIHELPERS, these are GUI tools and shouldn't be co-located with the app function. 

```C++

#define GUIHELPERS

#include "Isis.h"

#include "Application.h"

#include "app_func.h" // replace with your new header

using namespace Isis;

using namespace std;

void helper();

// this map and function definitions are ripped directly from the old main.cpp

map <QString, void *> GuiHelpers() {

  map <QString, void *> helper;

  helper ["Helper"] = (void *) helper;  

  return helper;

}

void IsisMain() {   // this may change depending on whether logs are needed or not

  UserInterface &ui = Application::GetUserInterface();

  app_func(ui);

}

void helper() {

	// whatever

}

```

### Application.h Template 

This almost never changes between applications. 

```C++

#ifndef app_name_h // Change this to your app name in all lower case suffixed with _h (e.g. campt_h, cam2map_h etc.)

#define app_name_h

#include "Cube.h"

#include "UserInterface.h"

namespace Isis{

  extern void app_func(Cube *cube, UserInterface &ui, Pvl *log=nullptr);

  extern void app_func(UserInterface &ui, Pvl *log=nullptr);

}

#endif

```

### GTEST Templates 

```C++

#include "Fixtures.h"

#include "Pvl.h"

#include "PvlGroup.h"

#include "TestUtilities.h"

#include "app.h"

#include "gtest/gtest.h"

using namespace Isis;

static QString APP_XML = FileName("$ISISROOT/bin/xml/app.xml").expanded();

TEST_F(SomeFixture, FunctionalTestAppName) {

  // tempDir exists if the fixture subclasses TempTestingFiles, which most do

  QString outCubeFileName = tempDir.path() + "/outTemp.cub";

  QVector<QString> args = {"from="+ testCube->fileName(),  "to="+outCubeFileName};

  UserInterface options(APP_XML, args);

  try {

    appfoo_func(options);

  }

  catch (IException &e) {

    FAIL() << "Unable to open image: " << e.what() << std::endl;

  }

  // Assert some stuff

}

```

 No newline at end of file

A new ISIS3 class needs to have the following Doxygen tags filled out just above the class declaration, as in this example below:

```C++

   /**

    * @brief Add map templates to a project

    * Asks the user for a map template and copies it into the project.

    *

    * @author 2018-07-05 Summer Stapleton

    * @internal

    *    @history 2018-07-05 Summer Stapleton - Created ImportMapTemplateWorkOrder

    *                        class

    *

    */

    class ImportMapTemplateWorkOrder : public WorkOrder {....

```

Sometimes, classes are declared inside the header files for other classes.  This happens a lot in the $ISISROOT/src/qisis/objs directory where internal XmlHandler classes are defined to handle object serialization.

These classes need to be documented as well (as in this example from the ImageList header file):

```C++

    /**

       * This class is used to read an images.xml file into an image list

       *

       * @author 2012-07-01 Steven Lambright

       *

       * @internal

       */

      class XmlHandler : public XmlStackedHandler {

```

All dates need to be filled out the way they are in the examples above (YYYY-MM-DD).  Sometimes you will see dates in this format:  2012-??-???? or  ????-??-??.  Do not do this.  Also, do not put any dashes or

other symbols between the date and the name of the programmer.  If these documentation standards are not followed, PHP warnings get output when the nightly builds are run.

 No newline at end of file