Merge pull request #109 from jrcain-usgs/docs

name: build-docs

on:

  pull_request:

    branches:

      - main

  push:

    branches:

      - main

jobs:

  build-docs-job:

    runs-on: ubuntu-latest

    defaults:

      run:

        shell: bash -el {0}

    steps:

      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9

      - uses: conda-incubator/setup-miniconda@3b0f2504dd76ef23b6d31f291f4913fb60ab5ff3

        with:

          miniconda-version: "latest"

          activate-environment: knoten-docs

          environment-file: docs/environment.yml

          auto-activate-base: false

          auto-update-conda: true

      - name: Check doc build environment

        run: |

          conda list

      - name: Build Docs

        run: |

          cd docs

          sphinx-build -b html . public

 No newline at end of file

name: deploy-docs-aws

on:

  workflow_run:

    workflows: ["build-docs"]

    branches:

      - main

    types: 

      - completed

jobs:

  deploy-docs-aws-job-test:

    if: ${{ github.event.workflow_run.conclusion == 'success' }}

    runs-on: ubuntu-latest

    defaults:

      run:

        shell: bash -el {0}

    steps:

      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9

      - uses: conda-incubator/setup-miniconda@3b0f2504dd76ef23b6d31f291f4913fb60ab5ff3

        with:

          miniconda-version: "latest"

          activate-environment: knoten-docs

          environment-file: docs/environment.yml

          auto-activate-base: false

          auto-update-conda: true

      - name: Check doc build environment

        run: |

          conda list

      - name: Build Docs

        run: |

          cd docs

          sphinx-build -b html . public

      - name: Set AWS credentials for upload

        uses: aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83

        with:

          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}

          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

          aws-region: us-west-2

      # - name: Upload to S3

      #   working-directory: docs

      #   run: aws s3 sync --delete public s3://asc-public-docs/knoten

 No newline at end of file

print.prt

*.cub

*.CUB

.DS_Store

 No newline at end of file

## Installing

You can install the latest build via conda

You can install the latest build via conda. 

```

conda install -c usgs-astrogeology -c conda-forge knoten

```

You can also do a local install using the following steps within a clone of the repository

You can also do a local install using the following steps within a clone of the repository.

1. Install the dependencies

1. Install the dependencies.  

   Note: creating the environment may take around and hour.  If conda is too slow, try using mamba instead.

    ```

    conda env create -f environment.yml

    ```

2. Install the package

1. Install the package

    ```

    python setup.py install

    ```

<hr>

## Building Docs

To build the docs:

1. Open the docs directory: `cd docs`

1. Create (if not existing) and activate the environment (or use the main knoten environment if it is already created).

   ```sh

   conda env create -f environment.yml #If it does not exist already

   conda activate knoten-docs

   ```

1. Run `sphinx-build -b html . public` to build the docs in the `docs/public` directory (or change "public" to a subdirectory name of your choosing).

1. Browse to the `index.html` file in `docs/public` to open the docs.  If needed, run a utility like `http-server` in the `docs/public` directory to serve the docs on localhost.

<hr>

## Status Report - November 2019

For full testing reports and example usage, please see the linked example Jupyter notebooks in the table below. 

{% extends '!layout.html' %}

{% block footer %}

    <!-- {{ super() }} -->

    {% include "usgsfooter.html" %}

{% endblock %}

{% block header %}

    {% include "usgsheader.html" %}

    {{ super() }}

{% endblock %}

 No newline at end of file