docs: readme and more like tacc-docs (#123)

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# How to Contribute
+
+We are glad you are reading this. We welcome your contribution.
+
+Here are some important resources:
+
+* [Known Issues](https://github.com/TACC/TACC-Docs/issues)
+* [Active Proposals](https://github.com/TACC/TACC-Docs/pulls)
+* [How to Test](./TESTING.md)
+
+## Step by Step
+
+[How to Contribute to **Use Cases**.](https://github.com/DesignSafe-CI/DS-User-Guide/blob/main/user-guide/docs/usecases/README.md)
+
+How to Contribute **Other Changes**:
+
+1. [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) this repository.\
+    <sup>(unless you are a direct collaborator)</sup>
+2. [Edit](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) relevant files that need update.\
+    <sup>([upload images](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository) as necessary)</sup>
+4. [Commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) your changes.\
+    <sup>(write [clear commit messages](#writing-commit-messages))</sup>
+5. [Test](#testing) your changes.\
+    <sup>(if comfortable using a command prompt)</sup>
+6. [Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) a review.\
+    <sup>(a.k.a. create a "Pull Request")</sup>
+
+## Writing Commit Messages
+
+Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:
+
+> **A brief summary of the commit**
+
+> A paragraph describing what changed and its impact.
+
+## Style Guide
+
+Start reading our newer docs and you'll get the hang of it. We optimize for readability:
+
+* We add a new line before starting a list
+* We indent using tab character
+* We create lists with asterisks
+* We should use [Markdown](https://www.markdownguide.org/extended-syntax/) where available[^1]
+* We use some [Python-Markdown extensions](https://python-markdown.github.io/extensions/) and [PyMdown exensions](https://facelessuser.github.io/pymdown-extensions/#extensions)[^2]
+* Use `cwd`-relative paths to images e.g. instead of `/hpc/imgs/blah.gif`, use `../imgs/blah.gif`.[^3]
+
+[^1]: If some of our documents use HTML, please forgive us and use Markdown yourself.
+[^2]: See enabled extensions at [`mkdocs.base.yml`](https://github.com/TACC/TACC-Docs/blob/main/mkdocs.base.yml) under `markdown_extensions:`.
+[^3]: So that images load on the website **and** in GitHub preview.
+
+Thanks,\
+Texas Advanced Computing Center

PUBLISHING.md

@@ -0,0 +1,22 @@
+# How to Publish
+
+> [!TIP]
+> Any merge (or commit) to `main` branch will publish the documentation.
+
+All commits to `main` will trigger a Docker build and push a new image to `taccwma/tacc-docs:latest`.
+
+A Watchtower service will monitor new pushes to this dockerhub repo and pull down new images _on the fly_ to [https://designsafe-ci.org/user-guide/](https://designsafe-ci.org/user-guide/).
+
+## Automation
+
+* Automatic build for every commit to `main` branch
+* Automatic deploy for every build off `main` branch
+* Manually build via [GitHub Actions](https://github.com/DesignSafe-CI/DS-User-Guide/actions)
+* Manually deploy via [internal process](https://tacc-main.atlassian.net/wiki/x/aBhv)
+
+## Releases
+
+[Releases](https://github.com/DesignSafe-CI/DS-User-Guide/releases) are made when a significant set of **functional** Pull Requests have been merged.
+
+> [!NOTE]
+> Releases are only used by clients of the TACC MkDocs [configuration](https://github.com/DesignSafe-CI/DS-User-Guide/blob/v0.14.0/mkdocs.base.yml) and [theme](https://github.com/DesignSafe-CI/DS-User-Guide/tree/v0.14.0/themes/tacc-readthedocs), so changes to the content of documents do **not** merit a release.

README.md

@@ -1,95 +1,21 @@
-# DesignSafe User Guide
+# TACC Docs
 
-DesignSafe [MkDocs](https://mkdocs.readthedocs.io/) documentation with **customized** [ReadTheDocs](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) theme.
+Built with [MkDocs](https://mkdocs.readthedocs.io/) and a **customized** [ReadTheDocs](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) theme.
 
 ## Contributing
 
-[How to Contirbute to **Use Cases**](https://github.com/DesignSafe-CI/DS-User-Guide/blob/main/user-guide/docs/usecases/README.md)
+We welcome contributions, offer a guide for those new to GitHub, and a style guide to simplify reviews. [Read more](./CONTRIBUTING.md) or skip to:
 
-How to Contribute **Other Changes**:
-
-1. [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) this repository.\
-    <sup>(unless you are a direct collaborator)</sup>
-2. [Edit](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) relevant files that need update.\
-    <sup>([upload images](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository) as necessary)</sup>
-4. [Commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) your changes.
-5. [Test](#testing) your changes.\
-    <sup>(if comfortable using a command prompt)</sup>
-6. [Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) a review.\
-    <sup>(a.k.a. create a "Pull Request")</sup>
-
-### Resources
-
-* [Markdown syntax (extended)](https://www.markdownguide.org/extended-syntax/) via [MkDocs' Markdown support](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown)
-    - plus some[^1] enabled [Python-Markdown extensions](https://python-markdown.github.io/extensions/)
-    - plus some[^1] enabled [PyMdown exensions](https://facelessuser.github.io/pymdown-extensions/#extensions)
-
-[^1]: Enabled extensions are tracked by https://github.com/TACC/TACC-Docs/blob/main/mkdocs.base.yml under `markdown_extensions:`.
+[How to Contribute to **Use Cases**.](user-guide/docs/usecases/README.md)
 
 ## Testing
 
-- [A. Via Python](#a-via-python)
-- [B. Via Docker](#b-via-docker)
-
-### A. Via Python
-
-0. Have [Python](https://www.python.org/) installed.\
-    <sup>Known supported versions are [from 3.10 to 3.12](https://github.com/TACC/TACC-Docs/blob/v0.10.1/pyproject.toml#L9).</sup>
-1. [Install Poetry](https://python-poetry.org/docs/#installation) to manage dependencies.\
-    <sup>You should only need to do this once.</sup>
-2. Navigate into `user-guide/` within your clone of this repo.
-3. Install/Update project dependencies:\
-    <sup>You should only need to do this after new releases.</sup>
-    ```shell
-    ../bin/tacc-setup.sh
-    poetry install --sync
-
-    ```
-4. Serve the docs:
-    ```shell
-    poetry shell
-    mkdocs serve
-
-    ```
-    <sup>After the `poetry shell` command, you should be in a Poetry-managed environment. Your prompt might be prefixed with the name of the environment.</sup>
-5. Open the website _at the URL echoed by the program_ e.g.
-    [http://127.0.0.1:8000/user-guide/](http://127.0.0.1:8000/user-guide/).
-
-### B. Via Docker
-
-0. Have Docker installed.\
-    <sup>We recommend doing so via [Docker-Desktop](https://www.docker.com/products/docker-desktop).</sup>
-1. Navigate into your clone of this repository.
-2. Start the Docker container to serve the docs.
-
-   Using `Make`:
-   ```shell
-    make build
-    make start
-
-    ```
-   Or:
-   ```shell
-    docker compose build
-    docker compose up
-
-    ```
-4. Open the website at the URL provided e.g.
-    [http://localhost:8000/user-guide/](http://localhost:8000/user-guide/).
-
-
-[^2]: To manually build or deploy, consult [our internal documentation](https://tacc-main.atlassian.net/wiki/x/aBhv).
-
-## Automatic Builds
-
-Automatic builds (not deploys) should occur on pushes to any branch.[^2]
-
-## Automatic Deployment
+Testing is manual and requires using a command prompt. You can test [via Python](./TESTING.md#a-via-python) or [via Docker](./TESTING.md#b-via-docker).
 
-Automatic deploys should occur after an automatic build on the `main` branch.[^2]
+## Publishing
 
-## Releases
+We automatically publish `main` branch commits. We manually release versions of TACC-Docs. [Read more](./PUBLISHING.md).
 
-All commits to `main` will trigger a docker build and push a new image to `designsafeci/ds-user-guide:latest`.
+## Theming
 
-A Watchtower service monitors new pushes to this dockerhub repo and pull down new images on the fly to [https://designsafeci-dev.tacc.utexas.edu/user-guide/](https://designsafeci-dev.tacc.utexas.edu/user-guide/).
+To theme your documentation like this project, please contact [@wesleyboar](https://www.github.com/wesleyboar) or mimic [DS-User-Guide](https://github.com/DesignSafe-CI/DS-User-Guide/).

TESTING.md

@@ -0,0 +1,48 @@
+## How to Test
+
+- [A. Via Python](#a-via-python)
+- [B. Via Docker](#b-via-docker)
+
+### A. Via Python
+
+0. Have [Python](https://www.python.org/) installed.\
+    <sup>Known supported versions are [from 3.10 to 3.12](https://github.com/TACC/TACC-Docs/blob/v0.10.1/pyproject.toml#L9).</sup>
+1. [Install Poetry](https://python-poetry.org/docs/#installation) to manage dependencies.\
+    <sup>You should only need to do this once.</sup>
+2. Navigate into your clone of this repo.
+3. Install/Update project dependencies:\
+    <sup>You should only need to do this after new releases.</sup>
+    ```shell
+    poetry install --sync
+    ```
+4. Activate project dependencies:\
+    ```shell
+    poetry shell
+    ```
+    <sup>After the `poetry shell` command, you should be in a Poetry-managed environment. Your prompt might be prefixed with the name of the environment.</sup>
+5. Serve the docs:\
+    ```shell
+    mkdocs serve
+    ```
+6. Open the website _at the URL echoed by the program_ e.g.
+    [http://127.0.0.1:8000/](http://127.0.0.1:8000/).
+
+### B. Via Docker
+
+0. Have Docker installed.\
+    <sup>We recommend doing so via [Docker-Desktop](https://www.docker.com/products/docker-desktop).</sup>
+1. Navigate into your clone of this repository.
+2. Start the Docker container to serve the docs.
+
+   Using `Make`:
+   ```shell
+    make build
+    make start
+    ```
+   Or:
+   ```shell
+    docker compose build
+    docker compose up
+    ```
+3. Open the website at the URL provided e.g.
+    [http://localhost:8000/](http://localhost:8000/).