Skip to content

Latest commit

 

History

History
105 lines (75 loc) · 4.43 KB

README.md

File metadata and controls

105 lines (75 loc) · 4.43 KB

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

Testing

A. Via Python

Important

This method has different theme than live website (#42) and bugs (#66).

  1. Have Python installed.
    Known supported versions are from 3.10 to 3.12.
  2. Navigate into your clone of this repo.
  3. Install software to manage dependencies:
    You should only need to do this once.
    pip install poetry
    
  4. Install/Update dependencies:
    You should only need to do this after new releases.
    ./bin/tacc-setup.sh
    poetry install
    
  5. Serve the docs:
    poetry shell
    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.
  6. 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 method does not work on macOS with an M1 nor M2 chip (details).

  1. Have Docker installed.
    We recommend doing so via Docker-Desktop.

  2. Navigate into your clone of this repository.

  3. Start the Docker container to serve the docs.

    Using Make:

     make build
     make start
    

    Or:

     docker compose build
     docker compose up
    
  4. Open the website at the URL provided e.g. http://0.0.0.1:8000/user-guide/.

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

Footnotes

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

  2. To manually build or deploy, consult our internal documentation. 2