DesignSafe User Guide

DesignSafe MkDocs documentation with customized ReadTheDocs theme.

Contributing

[!NOTE] For a detailed walkthrough of how to contribute to Use Cases, see its README.

1. Fork this repository.\ ^{(unless you are a direct collaborator)}
2. Edit relevant files that need update.\ ^{(upload images as necessary)}
3. Commit your changes.
4. Test your changes.\ ^{(if comfortable using a command prompt)}
5. Request a review.\ ^{(a.k.a. create a "Pull Request")}

Resources

• Markdown syntax (extended) via MkDocs' Markdown support
  • plus some[^1] enabled Python-Markdown extensions
  • plus some[^1] enabled PyMdown exensions

[^1]: Enabled extensions are tracked by https://github.com/TACC/TACC-Docs/blob/main/mkdocs.base.yml under markdown_extensions:.

Testing

• A. Via Python
• B. Via Docker

A. Via Python

[!IMPORTANT] This solution uses a different theme than designsafe-ci.org/user-guide (details).

0. Have Python installed.\ ^{Known supported versions are from 3.10 to 3.12.}
1. Navigate into your clone of this repo.

2. Install dependencies:\ ^{You should only need to do this once, or after a new release.}

   ./bin/tacc-setup.sh
   pip install poetry
   

3. Isolate dependencies:

   poetry shell
   

4. Update & Serve the docs:

   poetry install
   cd user-guide
   mkdocs serve
   

   ^{After the poetry shell command, you should be in a Poetry-managed environment. Your prompt might be prefixed with the name of the environment.}

5. Open the website at the URL echoed by the program e.g. http://127.0.0.1:8000/user-guide/.

B. Via Docker

[!WARNING] This solution does not work on macOS with an M1 nor M2 chip (details).

0. Have Docker installed.\ ^{We recommend doing so via Docker-Desktop.}
1. Navigate into your clone of this repository.

2. Start the Docker container to serve the docs.

   Linux or Mac (macOS) user:

   make build
   make start
   

   Windows user:

   docker-compose -f docker-compose.yml build
   docker-compose -f docker-compose.yml up
   

3. Open the website at the URL provided e.g. http://0.0.0.1:8000/user-guide/.

[^2]: To manually build or deploy, consult our internal documentation.

Automatic Builds

Automatic builds (not deploys) should occur on pushes to any branch.[^2]

Automatic Deployment

Automatic deploys should occur after an automatic build on the main branch.[^2]

Releases

All commits to main will trigger a docker build and push a new image to designsafeci/ds-user-guide:latest.

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