Skip to content

Commit

Permalink
Changed markdown + links in /docs/contribute
Browse files Browse the repository at this point in the history
  • Loading branch information
@atteggiani
atteggiani committed Apr 26, 2024
1 parent d7415f1 commit 0e4fd94
Show file tree
Hide file tree
Showing 4 changed files with 33 additions and 62 deletions.
79 changes: 31 additions & 48 deletions docs/about/contribute/contribute_on_github.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,39 @@
<div class="flex-container with-border with-padding">
<div class="med-text bold">Prerequisites</div>
<br>
<div>
<i class="fa-regular fa-square-check nri-green-color with-padding"></i> If are new to GitHub, you will first need to <a href="https://github.com" target="_blank">sign up</a> for a GitHub account.
<br>
<i class="fa-regular fa-lightbulb nri-orange-color with-padding"></i>
For learning GitHub, we also encourage you to complete <a href="#additional-github-learning-resources" target="_blank">self-paced GitHub learning courses</a> for brushing up basic GitHub skills.
<br>
<br>
<div class="markdown-notes">
<b>Note:</b> Please note that you <i>do not</i> need to complete all these learning courses before making your first contribution. The first
<b>"Introduction to Github"</b> course should make you well-equipped for making your first contribution to the Hive!
</div>
</div>
</div>
# Contribute on GitHub

## Prerequisites
:fontawesome-regular-square-check:{: style="color:var(--nri-green)" } If you are new to GitHub, you will first need to [sign up](https://github.com) for a GitHub account.

:material-head-lightbulb-outline:{: style="color:var(--nri-orange)" } We also encourage you to complete [self-paced GitHub learning courses](#additional-github-learning-resources) for brushing up basic GitHub skills.

## Let's get started!

This documentation is written in Markdown format and is based on the <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank">Material for MkDocs</a> theme, which is built on top of <a href="https://www.mkdocs.org" target="_blank">MkDocs</a> static site generator.
<br>
For a quick reference on how to use Markdown syntax you can refer to the <a href="https://www.markdownguide.org/cheat-sheet/" target="_blank">Markdown Cheat Sheet</a>.
This documentation is written in Markdown format and is based on the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)</a> theme, which is built on top of [MkDocs](https://www.mkdocs.org) static site generator.<br>
For a quick reference on how to use Markdown syntax you can refer to the [Markdown Cheat Sheet](https://www.markdownguide.org/cheat-sheet/).

## Raise a GitHub Issue

All contributions need to have an associated <a href="https://docs.github.com/en/issues/tracking-your-work-with-issues/" target="_blank">Github issue</a> that explains the content and importance of the contribution.
<br>
To raise an issue, create a New Issue in the <a href="https://github.com/ACCESS-Hive/access-hive.github.io/issues" target="_blank">ACCESS-Hive Github repository issue page</a>. Feel free to assign that issue to yourself if you intend to work on it.
All contributions need to have an associated [Github issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/)</a> that explains the content and importance of the contribution.<br>
To raise an issue, create a New Issue in the [ACCESS-Hive Github repository issue page](https://github.com/ACCESS-NRI/access-hive.org.au/issues). Feel free to assign that issue to yourself if you intend to work on it.

## Fork the ACCESS-Hive GitHub repository

After raising a Github issue about your contribution, you need to <a href="https://docs.github.com/en/get-started/quickstart/fork-a-repo?platform=mac&tool=webui" target="_blank">fork</a> the <a href="https://github.com/ACCESS-Hive/access-hive.github.io" target="_blank">ACCESS-Hive Github repository</a>.
After raising a Github issue about your contribution, you need to [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo?platform=mac&tool=webui) the [ACCESS-Hive Github repository](https://github.com/ACCESS-NRI/access-hive.org.au).

## Clone the forked ACCESS-Hive GitHub repository locally
For cloning the forked repository onto your local computer, we encourage you to first add your local SSH keys to your GitHub profile.

To start with, if you have an <a href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys" target="_blank">existing SSH key</a>, then simply <a href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account" target="_blank">add this key to your github account</a>, and you are all set to clone the repository. In case you don't have the SSH keys set up on your local computer, it's easy to <a href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent" target="_blank">create a new SSH key locally</a>, and then <a href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account" target="_blank">feel free to link this key to your github account</a>.
To start with, if you have an [existing SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys), then simply [add this key to your github account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account), and you are all set to clone the repository. In case you don't have the SSH keys set up on your local computer, it's easy to [create a new SSH key locally](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent), and then [feel free to link this key to your github account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).

<terminal-window>
<terminal-line data="input">git clone [email protected]:ACCESS-Hive/access-hive.github.io.git</terminal-line>
<terminal-line data="input">git clone [email protected]:ACCESS-NRI/access-hive.org.au.git</terminal-line>
<terminal-line></terminal-line>
<terminal-line>Cloning into 'access-hive.github.io'...</terminal-line>
<terminal-line>remote: Enumerating objects: 54754, done.</terminal-line>
<terminal-line>remote: Counting objects: 100% (4096/4096), done.</terminal-line>
<terminal-line>remote: Compressing objects: 100% (560/560), done.</terminal-line>
<terminal-line>remote: Total 54754 (delta 2178), reused 4053 (delta 2155), pack-reused 50658</terminal-line>
<terminal-line>Receiving objects: 100% (54754/54754), 103.15 MiB | 6.97 MiB/s, done.</terminal-line>
<terminal-line>Resolving deltas: 100% (28610/28610), done.</terminal-line>
<terminal-line>remote: Enumerating objects: 54754, done.</terminal-line>
<terminal-line>remote: Counting objects: 100% (4096/4096), done.</terminal-line>
<terminal-line>remote: Compressing objects: 100% (560/560), done.</terminal-line>
<terminal-line>remote: Total 54754 (delta 2178), reused 4053 (delta 2155), pack-reused 50658</terminal-line>
<terminal-line>Receiving objects: 100% (54754/54754), 103.15 MiB | 6.97 MiB/s, done.</terminal-line>
<terminal-line>Resolving deltas: 100% (28610/28610), done.</terminal-line>
</terminal-window>

## Make changes locally
Expand All @@ -55,14 +43,15 @@ After cloning the repository locally, create a new branch to make your local cha
<terminal-line data="input">git checkout -b spongebob/fix-hive-title-issue-234</terminal-line>
<terminal-line>Switched to a new branch 'spongebob/fix-hive-title-issue-234'</terminal-line>
</terminal-window>

<terminal-window>
<terminal-line data="input">git push --set-upstream origin spongebob/fix-hive-title-issue-234</terminal-line>
<terminal-line>Total 0 (delta 0), reused 0 (delta 0), pack-reused 0</terminal-line>
<terminal-line>remote: </terminal-line>
<terminal-line>remote: Create a pull request for 'spongebob/fix-hive-title-issue-234' on GitHub by visiting:</terminal-line>
<terminal-line>remote: https://github.com/ACCESS-Hive/access-hive.github.io/pull/new/spongebob/fix-hive-title-issue-234</terminal-line>
<terminal-line>remote: https://github.com/ACCESS-NRI/access-hive.org.au/pull/new/spongebob/fix-hive-title-issue-234</terminal-line>
<terminal-line>remote: </terminal-line>
<terminal-line>To github.com:ACCESS-Hive/access-hive.github.io.git</terminal-line>
<terminal-line>To github.com:ACCESS-NRI/access-hive.org.au.git</terminal-line>
<terminal-line>* [new branch] spongebob/fix-hive-title-issue-234 -> spongebob/fix-hive-title-issue-234</terminal-line>
<terminal-line>branch 'spongebob/fix-hive-title-issue-234' set up to track 'origin/spongebob/fix-hive-title-issue-234'.</terminal-line>
</terminal-window>
Expand All @@ -84,15 +73,15 @@ Work locally on the branch `spongebob/fix-hive-title-issue-234`, and push the co
<terminal-line>Writing objects: 100% (6/6), 637 bytes | 637.00 KiB/s, done.</terminal-line>
<terminal-line>Total 6 (delta 5), reused 0 (delta 0), pack-reused 0</terminal-line>
<terminal-line>remote: Resolving deltas: 100% (5/5), completed with 5 local objects.</terminal-line>
<terminal-line>To github.com:ACCESS-Hive/access-hive.github.io.git</terminal-line>
<terminal-line>To github.com:ACCESS-NRI/access-hive.org.au.git</terminal-line>
<terminal-line>7263feb5..7afe8c13 spongebob/fix-hive-title-issue-234 -> spongebob/fix-hive-title-issue-234</terminal-line>
</terminal-window>

While working on a local branch, please make sure to regularly pull changes from the remote `main` into your local branch, as follows:

<terminal-window>
<terminal-line data="input">git pull origin main</terminal-line>
<terminal-line>From github.com:ACCESS-Hive/access-hive.github.io</terminal-line>
<terminal-line>From github.com:ACCESS-NRI/access-hive.org.au</terminal-line>
<terminal-line>* branch main -> FETCH_HEAD</terminal-line>
<terminal-line>Already up to date.</terminal-line>
</terminal-window>
Expand All @@ -102,7 +91,7 @@ This would make sure that the local branch `spongebob/fix-hive-title-issue-234`
## Deploying Website Preview
MkDocs includes a live preview server, so you can preview your changes as you write your documentation. The server will automatically rebuild the site upon saving.

To build the site locally, you need to install <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank">Material for MkDocs</a> and other plugins. You can find a ful list in the `requirements.txt` file (in the root of the <a href="https://github.com/ACCESS-Hive/access-hive.github.io/" target="_blank">ACCESS-Hive GitHub repository</a>). Please use `pip` for the installation as some of the packages are not updated or not available on conda:
To build the site locally, you need to install [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and other plugins. You can find a ful list in the `requirements.txt` file (in the root of the [ACCESS-Hive GitHub repository](https://github.com/ACCESS-NRI/access-hive.org.au)). Please use `pip` for the installation as some of the packages are not updated or not available on conda:

<terminal-window>
<terminal-line data="input">pip install -r requirements.txt</terminal-line>
Expand All @@ -127,21 +116,15 @@ Your documentation will be built on http://127.0.0.1:8000. Open this URL in your

## Create a Pull Request for the final changes

Once the changes on your local branch `spongebob/fix-hive-title-issue-234` are ready to be integrated with the `development` branch, <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request" target="_blank">create a pull request</a> and GitHub will automatically build a preview of the documentation using <a href="https://docs.github.com/en/actions" target="_blank">GitHub Actions</a>.

<img src="/assets/github-preview-link.png">

<div class="markdown-notes">
<b>Note:</b> It can take a while for the preview to build, even after the CI check is indicated as "finished". Please wait for the comment with the link to appear and allow for some time after that for the preview to be properly deployed.
Once the changes on your local branch `spongebob/fix-hive-title-issue-234` are ready to be integrated with the `development` branch, [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) and GitHub will automatically build a preview of the documentation using [GitHub Actions](https://docs.github.com/en/actions).

If you open the preview and it looks completely broken or if it hasn't updated from additional modifications in the pull reuqest, it probably means the site hasn't finished building yet. If you wait a couple of minutes and refresh the page, it should fix itself.
</div>
![GitHub preview](/assets/github-preview-link.png){: class="example-img" }

After a PR is created and tested, feel free to ask for reviews by tagging the ACCESS-Hive/reviewers team and reply if any changes are being requested in the PR.

## Additional GitHub learning resources

- <a href="https://github.com/skills/introduction-to-github" target="_blank">Introduction to GitHub</a>
- <a href="https://docs.github.com/en/get-started/quickstart/set-up-git" target="_blank">Setting up Git</a>
- <a href="https://docs.github.com/en/get-started/quickstart/github-flow" target="_blank">GitHub workflow</a>
- <a href="https://github.com/skills/communicate-using-markdown" target="_blank">Using Markdown</a>
- [Introduction to GitHub](https://github.com/skills/introduction-to-github)
- [Setting up Git](https://docs.github.com/en/get-started/quickstart/set-up-git)
- [GitHub workflow](https://docs.github.com/en/get-started/quickstart/github-flow)
- [Using Markdown](https://github.com/skills/communicate-using-markdown)
2 changes: 1 addition & 1 deletion docs/about/contribute/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contribute to ACCESS-Hive

<img class="intro-img img-cover with-border" src="/assets/github-how-to-contribute.jpg" loading="lazy"/ style="object-position: ">
![Contribute image](/assets/github-how-to-contribute.jpg){: class="intro-img img-cover with-border" loading="lazy"}

ACCESS-Hive is an open user portal which hosts the documentation relevant to the Australian Community Climate and Earth System Simulator (ACCESS) community.

Expand Down
2 changes: 1 addition & 1 deletion docs/community_resources/community_med/community_data_processing.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Community Processing Data Processing Tools

???+ danger "Support Level: NOT supported by ACCESS-NRI"
Here, we collate lists of useful tools for Model Evaluation and Diagnostics (MED). Contrary to the supported content of our [ACCESS-NRI Model Evaluation pages](../../model_evaluation/index.md), the information below is not supported by ACCESS-NRI unless stated otherwise.
Here, we collate lists of useful tools for Model Evaluation and Diagnostics (MED). The information below is not supported by ACCESS-NRI unless stated otherwise.

Please let us know, if we are missing an important tool. Check [How To Contribute](/about/contribute) to get in touch.

Expand Down
12 changes: 0 additions & 12 deletions docs/css/access-nri.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1038,18 +1038,6 @@ img.intro-img {
height: 20em;
}


/*
For formatting a `> Note:` markdown syntax in html
*/
.markdown-notes {
/* color: var(--tab-text-light); */
color: var(--md-default-fg-color--light);
border-left: 0.2em solid var(--md-default-fg-color--lighter);
padding: 0.3em 0.9em;
margin: 0 0.6em;
}

.green_prompt_output {
color: #00C202
}
Expand Down

0 comments on commit 0e4fd94

Please sign in to comment.