Getting Started

This repository is the place where all St. Jude Cloud documentation lives or will eventually live. The St. Jude Cloud documentation is built using mkdocs as the site generation package and a modified version of the mkdocs-material theme. All changes to the documentation are processed through GitHub Pull Requests, the same way as many open source projects operate. We welcome pulls from anyone in the community. If you have questions, please contact us.

Install Dependencies

The following software is required for writing St. Jude Cloud technical documentation. Please click on the install links for each of the software below and ensure that the install process completes for each.

Dependency	Links	Notes
Git	Install	Windows: install with default settings
Python 3	Install	Windows: ensure you select the "Add to PATH" option
Visual Studio Code (Recommended)	Install
ConEmu (Recommended for Windows)	Install	Use instead of cmd.exe

Writing

Writing documentation for St. Jude Cloud looks a little different based on whether you are on a Windows machine, a Mac machine, or a Linux machine. If you are not familiar with developing documentation using mkdocs please click the appropriate platform below and execute the steps in the order listed.

• Windows
• Mac/Linux

Windows

One-time Setup

1. Open a command prompt by clicking the Start button and typing cmd.exe (or conemu.exe, if you are using the recommended terminal program).
2. Type git and press <Enter>. You should see a long usage guide as output. If you see something resembling 'command not found', please ensure that you've installed git correctly.
3. If you have not already, follow this guide to configure your GitHub account with an SSH key. If you are a St. Jude employee, you will also need to authorize your ssh key to work with SAML.
4. Run git clone [email protected]:stjude/sjcloud-docs.git to get a local copy of the repository that you can work inside.
5. Run cd sjcloud-docs to change to the correct directory.
6. Run pip install -r requirements.txt to install all of the dependencies of the project.

Writing Documentation

1. In the sjcloud-docs directory, Run mkdocs serve. This command will run in the background for as long as you are developing the documentation.
2. If it does not open up automatically after 10 or so seconds, open your web browser to http://localhost:8000. You should see the documentation rendered as an HTML page.
3. Start the Visual Studio Code editor (or your favorite editor) and open the sjcloud-docs folder.
4. As you make changes to the documentation, you should see the HTML update in the browser (after reloading the page).

Build a Static Site

Please ensure that you have finished the "Setup Environment" pages above.

1. In the sjcloud-docs directory, run the mkdocs build command. Unless you specify otherwise, the site will be built to a directory called "site".

Mac/Linux

One-time Setup

1. Open a terminal by pressing <Command-Space>, typing "Terminal", and pressing <Enter>.
2. Type git and press <Enter>. You should see a long usage guide as output. If you see something resembling 'command not found', please ensure that you've installed git correctly.
3. If you have not already, follow this guide to configure your GitHub account with an SSH key. If you are a St. Jude employee, you will also need to authorize your ssh key to work with SAML.
4. Run git clone [email protected]:stjude/sjcloud-docs.git to get a local copy of the repository that you can work inside.
5. Run cd sjcloud-docs to change to the correct directory.
6. Run pip install -r requirements.txt to install all of the necessary Python dependencies.

Writing Documentation

Please ensure that you have finished the "Setup Environment" pages above.

1. In the sjcloud-docs directory, Run mkdocs serve. This command will run in the background for as long as you are developing the documentation.
2. If it does not open up automatically after 10 or so seconds, open your web browser to http://localhost:8000. You should see the documentation rendered as an HTML page.
3. Start the Visual Studio Code editor (or your favorite editor) and open the sjcloud-docs folder.
4. As you make changes to the documentation, you should see the HTML update in the browser (after reloading the page).

Build a Static Site

Please ensure that you have finished the "Setup Environment" pages above.

1. In the sjcloud-docs directory, run the mkdocs build command. Unless you specify otherwise, the site will be built to a directory called "site".