Skip to content

Commit

Permalink
Merge pull request #685 from ACCESS-NRI/development
Browse files Browse the repository at this point in the history 
Periodical merge
  • Loading branch information
@atteggiani
atteggiani authored May 10, 2024
2 parents efd06c3 + c3eb4f2 commit 78f9610
Show file tree
Hide file tree
Showing 68 changed files with 2,307 additions and 2,167 deletions.
48 changes: 18 additions & 30 deletions .github/workflows/check_links.yml
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,26 @@
name: Check Markdown links
name: Check links

on:
push:
schedule:
# Run at 03:07 every Sunday
- cron: "7 3 * * SUN"
pull_request: #Action fires anytime a PR is (re)opened or synchronized
types:
- opened
- reopened
- synchronize
schedule:
# Run every Sunday at 03:07 (AEDT)
# AEDT is UTC+10 --> Sunday at 03:07 AEDT is Saturday at 17:07 UTC
- cron: "7 17 * * SAT"
workflow_dispatch:

jobs:
markdown-link-check:
if: ${{ github.event_name != 'schedule' }}
link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: gaurav-nelson/github-action-markdown-link-check@v1
- name: Checkout repo
uses: actions/checkout@master

- name: Link checker
uses: lycheeverse/[email protected]
with:
config-file: '.github/workflows/mlc_config.json'
folder-path: 'docs'
# Only check links in modified files to reduce false positives
check-modified-files-only: 'yes'
use-quiet-mode: 'no'
use-verbose-mode: 'yes'
base-branch: 'main'

scheduled-markdown-link-check:
if: ${{ github.event_name == 'schedule' }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: gaurav-nelson/github-action-markdown-link-check@v1
with:
use-quiet-mode: 'no'
use-verbose-mode: 'yes'
config-file: '.github/workflows/mlc_config.json'
folder-path: 'docs'
base-branch: 'main'

fail: true
args: --config .github/workflows/lychee-config.toml './docs/**/*.md' './docs/**/*.html'
39 changes: 39 additions & 0 deletions .github/workflows/lychee-config.toml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Configuration file for lychee link-checker (https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml)

# Exclude URLs and mail addresses from checking (supports regex).
exclude = [
'^https://code\.metoffice\.gov\.uk',
'^https://web\.archive\.org/web/',
'^http://127\.0\.0\.1:8000',
'^https://www.linkedin.com/',
]

# Exclude these filesystem paths from getting checked.
exclude_path = [
"./docs/fontello",
"./docs/fontawesome*",
]

# Set verbose level
verbose = "info"

# Don't show interactive progress bar while checking links.
no_progress = true

# Enable link caching. This can be helpful to avoid checking the same links on
# multiple runs.
cache = true

# Discard all cached requests older than this duration.
max_cache_age = "3d"

# Base URL or website root directory to check relative URLs.
base = "https://access-hive.org.au/"

# Check links inside `<code>` and `<pre>` blocks as well as Markdown code
# blocks.
include_verbatim = true

# Check mail addresses
include_mail = true

139 changes: 72 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,81 +2,86 @@
[![ACCESS-Hive Badge](docs/assets/badge.svg)][website]
[![github-contributors](https://img.shields.io/github/contributors/ACCESS-Hive/access-hive.github.io?color=blue&style=plastic)][github-repo]
[![forum-users](https://img.shields.io/discourse/users?color=blue&label=forum&server=https%3A%2F%2Fforum.access-hive.org.au&style=plastic)][forum]
[![link-check](https://github.com/ACCESS-NRI/access-hive.org.au/actions/workflows/link_check.yml/badge.svg)](https://github.com/ACCESS-NRI/access-hive.org.au/actions/workflows/link_check.yml)

Documentation hub for the Earth System models, ACCESS, and their community.

This repository uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to build the website which accessible at this URL:<br>
This repository is the implementation of the ACCESS-Hive website accessible at the following URL:<br>
https://access-hive.org.au/

ACCESS-Hive is the documentation hub for the Earth System models, ACCESS, and their community.

# How to Contribute
If you wish to add documentation to the ACCESS-Hive website see the [contribution guide](https://access-hive.org.au/about/contribute/) for instructions.
If you wish to add documentation to the ACCESS-Hive website check the [contribution guide](https://access-hive.org.au/about/contribute/) for instructions.

## Styling guidelines for developers
The ACCESS-Hive website is built using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). For detailed information on markdown syntax and different features, please refer to [mkdocs-material documentation](https://squidfunk.github.io/mkdocs-material/reference/).

## Styling guidelines for contribution
Please follow the guidelines below so as to make the Hive consistent among the pages contributed by different people.
Please follow the guidelines below to make the Hive consistent among all the pages contributed by different people.

- Always prefer HTML syntax to Markdown when possible;
- Always prefer Markdown syntax to HTML when possible;
- All internal URLs need to be ABSOLUTE links, starting with `/` which indicates the base website `https://access-hive.org.au/`. So, a reference to the page `https://access-hive.org.au/models/configurations/access-cm/` will be `/models/configurations/access-cm`. Also, all assets need to be linked starting with `/assets/...`. This because currently the link checker does not handle relative links properly.
- Titles/subtitles should NOT include: code lines/blocks, bold (titles are usually already bold), italic, links;
- Code lines/blocks need to be used for lines/blocks of code and terminal commands;
- Italic needs to be used when referring to specific proper nouns (for example *Gadi* or *Accessdev*);
- Code lines/blocks need to be used for lines/blocks of code, terminal commands and file/directory paths/names;
- Italic needs to be used when referring to specific proper nouns (for example _Gadi_ or _payu_);
- Bold can be used to highlight some words (please do not overuse it);
- Links should be coded using HTML syntax.<br>External links (links that go to a website other than https://access-hive.org.au) need to specify `target="_blank"` (see HTML cheatsheet below);
- To signal an important note within the text, consider using a "warning note" (see HTML cheatsheet below);
- Instructions for different versions (for example different operative systems or different model versions) can be rendered using tabs (see HTML cheatsheet below);


### HTML Cheatsheet for the Hive
|Style|HTML Syntax|Rendered example|
|---|---|---|
|**Bold**|\<b>bold\</b>|**bold**|
|**Italic**|\<i>italic\</i>|*italic*|
|**Code line**|\<code>this is a code line\</code>|`this is a code line`|
|**Code block**|\<pre>\<code>this is a code block\</code>\</pre>|<pre><code>this is a code block</code></pre>|
|**Link (internal)**|\<a href="https://access-hive.org.au">ACCESS-Hive link\</a>|<a href="https://access-hive.org.au">ACCESS-Hive link</a>|
|**Link (external)**|\<a href="https://www.google.com" target="_blank">Google link\</a>|<a href="https://www.google.com" target="_blank">Google link</a><span style="display: inline-block; color: #3894FF; margin-left: 1px; font-size: 8px; vertical-align: text-top; rotate: 90deg;">&#9099;</span>|
|**Warning note**|\<div class="note">this is a warning note\<div>|![warning note](docs/assets/assets_for_readme/warning_note.png)|
|**Tabs**|\<div class="tabLabels" label="your-tab-label">\<button>Tab1\</button>\<button>Tab2\</button>\</div>\<div class="tabContents" label="your-tab-label">\<div>Content for tab1\</div>\<div>Content for tab2\</div>\</div>|![tabs](docs/assets/assets_for_readme/tabs.gif)|

<!-- - Pull the latest version of `development` branch locally by using the following commands:
> Fetch the remote branches from github:
`git fetch`
> On terminal, switch to the `development` branch locally using the command:
`git switch development`
> Pull the latest changes from remote `development` branch locally:
`git pull`
- Once the latest version of `development` branch is pulled locally, use the following two commands to create the new branch and push it to github respectively:
`git checkout -b dev/jasmeen/legacy-release`
`git push --set-upstream origin dev/jasmeen/legacy-release`
- Prefixing the branch name with `dev/jasmeen` might be used as an indicator that this needs to merged in the `development` branch of access-hive (staging branch deployed on https://access-hive.org.au/development-website/), and _**not**_ the main branch.
- Work locally on the branch `dev/jasmeen/legacy-release`, and push the commits using the commands:
`git add .`
`git commit -m "First commit"`
`git push`
- While working locally on the branch, please make sure to regularly pull changes from remote `development` branch into your branch, using the command:
`git pull origin development`
This would make sure that the local branch `dev/jasmeen/legacy-release` is always in sync with the latest changes in the remote `development` branch.
- Once the changes on the local branch `dev/jasmeen/legacy-release` is ready to be integrated with the `development` branch, create a pull request on github by changing the `base` to `development`. (Please find the below screenshot). This would create a pr on the `development` branch.
![Screenshot 2023-06-02 at 2 05 13 pm](https://github.com/ACCESS-Hive/access-hive.github.io/assets/42607679/ec141fc9-ee00-4a84-ae5a-081761400765)
- All types of admonitions (info, warning, etc.), collapsible and not, can be used as described in the [documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/), but they are rendered slightly differently. For the HTML version of them, please refer to the [HTML/Markdown cheatsheet for the Hive](#htmlmarkdown-cheatsheet-for-the-hive).
- Instructions for different versions (for example different operative systems or different model versions) can be rendered using tabs (see [HTML/Markdown cheatsheet for the Hive](#htmlmarkdown-cheatsheet-for-the-hive));
- Terminal input/output examples can be rendered using [animated-terminal.js](https://github.com/atteggiani/animated-terminal.js)

### Styling Markdown using CSS
#### Attribute lists
To style Markdown using custom CSS, you can use [attribute lists](https://python-markdown.github.io/extensions/attr_list/#limitations) by adding the desired CSS style (in-line or adding classes as defined in the `access-nri.css` file) inside curly brackets (starting with a colon) right after the markdown syntax.

For example, to make an image 50%-wide and with rounded borders, you can write the following:
```
![image text](/image/url/){: style="width: 50%; border-radius: 0.6rem;" }
```
#### Markdown in HTML
You can use [Markdown in HTML](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/?h=md+in+html#markdown-in-html) by adding the `markdown` attribute inside an HTML tag.<br>
You can then style the HTML tag using CSS (in-line or adding selectors to the `access-nri.css` file).

For example, to render a markdown section with half font-size, you can write the following:
```
<div markdown style="font-size: 0.5em;">
### Section with half font-size (This will appear in the table of content)
- First _bullet_ point
- Second bullet **point**
</div>
```

### Custom HTML tags
Some custom HTML tags were created (in the `js/custom-tags.js` file) to facilitate the rendering of some components.<br>
The following custom tags are available:

- **"Not supported by ACCESS-NRI" admonition**<br>
The `<custom-not-supported/>` tag renders a preset "Not supported by ACCESS-NRI" admonition.

- **References**<br>
The `<custom-references> ... </custom-references>` tag renders references to be used at the bottom of a page. Each new line (created by pressing <kbd>return</kbd>/<kbd>Enter</kbd>) inside `...` is rendered as a separate bullet point. A hyphen (`-`) can included at the beginning of a new line (for clarity) but it is stripped off at the time of rendering.<br>
For example, to reference 2 links you can write:
```
<custom-references>
- [First reference](first-reference-url)
- [Second reference](second-reference-url)
</custom-references>
```

- **Simulated terminal info**<br>
The `<custom-simulated-terminal-info/>` tag renders a preset info admonition on the pages where simulated terminal are used.<br>
It should not be used manually as it is automatically embedded in the pages containing simulated terminals.


### HTML/Markdown Cheatsheet for the Hive
|Style|Markdown Syntax|HTML Syntax|Rendered example|
|---|---|---|---|
|**Bold**|\*\*bold**|\<b>bold\</b>|**bold**|
|**Italic**|\_italic_|\<i>italic\</i>|_italic_|
|**Code line**|\`code line`|\<code>code line\</code>|`code line`|
|**Code block**|\```<br>&emsp;code block<br>```|\<pre><br>&emsp;\<code>code block\</code><br>\</pre>|<pre><code>code block</code></pre>|
|**[Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) (not collapsible)**|!!! warning<br>&emsp;this is a warning admonition|\<div class="admonition warning"><br>&emsp;this is a warning<br>&emsp;admonition<br>\<div>|![warning admonition](docs/assets/assets_for_readme/warning_admonition.png)|
|**Collapsible [Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage)**|??? warning title<br>&emsp;this is a collapsible warning admonition|\<details class="warning"><br>&emsp;\<summary><br>&emsp;&emsp;\<p><br>&emsp;&emsp;&emsp;this is a collapsible<br>&emsp;&emsp;&emsp;warning admonition<br>&emsp;&emsp;\</p><br>&emsp;\</summary><br>\</details>|![collapsible warning admonition](docs/assets/assets_for_readme/collapsible_warning_admonition.gif)|
|**Tabs**|N/A|\<div class="tabLabels" label="your-tab-label"><br>&emsp;\<button>Tab1\</button><br>&emsp;\<button>Tab2\</button><br>\</div><br>\<div class="tabContents" label="your-tab-label"><br>&emsp;\<div><br>&emsp;&emsp;Content for tab1<br>&emsp;\</div><br>&emsp;\<div><br>&emsp;&emsp;Content for tab2<br>&emsp;\</div><br>\</div>|![tabs](docs/assets/assets_for_readme/tabs.gif)|

- When creating a pull request (PR) please also assign a reviewer to avoid delays. For technical content please assign an expert reviewer. -->

# License
The ACCESS-Hive site is covered by the [CC-BY 4.0 license](https://creativecommons.org/licenses/by/4.0/legalcode).
Expand All @@ -85,4 +90,4 @@ However, the material linked to from ACCESS-Hive is covered by various licensing

[website]: https://access-hive.org.au
[github-repo]: https://github.com/ACCESS-Hive/access-hive.github.io.git
[forum]: https://forum.access-hive.org.au
[forum]: https://forum.access-hive.org.au
48 changes: 14 additions & 34 deletions docs/about/License.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
[cc-by-human]: https://creativecommons.org/licenses/by/4.0/
[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode

# License

The ACCESS-Hive is made available under the [Creative Commons Attribution
Expand All @@ -6,45 +9,22 @@ license][cc-by-human]. The following is a human-readable summary of
license][cc-by-legal].

You are free to:
<ul>
<li>
<b>Share</b>
<br>
Copy and redistribute the material in any medium or format
</li>
<li>
<b>Adapt</b>
<br>
Remix, transform, and build upon the material
</li>
</ul>

- **Share**<br>
Copy and redistribute the material in any medium or format
- **Adapt**<br>
Remix, transform, and build upon the material

for any purpose, even commercially.

The licensor cannot revoke these freedoms as long as you follow the
license terms.

Under the following terms:
<ul>
<li>
<b>Attribution</b>
<br>
You must give appropriate credit (mentioning that your work is derived from work that is Copyright © ACCESS-NRI and, where practical, linking to **https://www.access-nri.org.au/**), provide a [link to the license][cc-by-human], and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
</li>
<li>
<b>No additional restrictions</b>
<br>
You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. With the understanding that:
<ul>
<li>
You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
</li>
<li>
No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
</li>
</ul>
</li>
</ul>

[cc-by-human]: https://creativecommons.org/licenses/by/4.0/
[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
- **Attribution**<br>
You must give appropriate credit (mentioning that your work is derived from work that is Copyright © ACCESS-NRI and, where practical, linking to **https://www.access-nri.org.au/**), provide a link to the [license][cc-by-human], and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
- **No additional restrictions**<br>
You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. With the understanding that:
- You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
- No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
Loading

0 comments on commit 78f9610

Please sign in to comment.