Creating the Documentation Template

Workflow for creating the documentation skeleton repository

Step 1: Clone the NMFS Open Science repository

This is done on the GitHub website and assumes the user already has a GitHub account and is signed in. These steps will duplicate the NOAA Open Science repo into that user’s account.

Navigate to the nmfs-opensci/NOAA-quarto-simple-python in a web browser.
Click the green “Use this template” button and select “Create a new repository”.

Select the “Include all branches” box. This is important to ensure everything works without any additional manual configuration.
Select a repo owner and provide a name for the new repo being created. We will refer to this repo as the template repo throughout these instructions. Enter a description, if desired. (This can be changed or added later.) Select “Public”.
Click “Create repository”.
In the newly created template repo, click “Settings” at the top of the page.
Select “Pages” on the side menu.
Enable GitHub Pages, if not already enabled, and note the URL at which the site is live. You can verify that everything worked by navigating to the site in a web browser. It should exactly like the original web book. Keep other settings unchanged and save any changes.

Step 2: Clone this new repo locally

One the main page of the new repo, click the green “< > Code” button.
Copy the HTTPS web URL shown in the popup.
On your local computer, in a terminal window or Command Prompt, navigate to where the repo is to be downloaded, and type
```
git clone <URL>
```
where <URL> is the web URL from Step 2.2 above.
Press enter. The repo will now be downloaded to your local machine.

Alternatively, after Step 2.1, either use the “Open with GitHub Desktop” or the “Download ZIP” options shown above to download the repo. Be sure to unzip it if you retrieve it this way.

Step 3: Add a new docs branch

The repo is currently configured to render the Quarto project on the main branch and publish the website to the gh-pages branch. To make this more suitable for code repositories, we will reserve the main branch for code and other project files and use a dedicated docs branch to host the Quarto website files.

Using a terminal or Command Prompt on your local computer, navigate to the new template repo directory.

Create a new docs branch and push to GitHub:

git checkout -b docs
git push origin docs

Clear out the main branch and return to docs:

```bash git checkout main rm -r . git commit -m “Remove all files from branch” git push origin main git checkout docs

From this point on, all template repo activity will refer to the docs branch unless otherwise noted. Next we’ll a second repo for the theme itself.