Update decoding_mom6.md

[chrisb13]

Notes taken by me for @angus-g and @jbisits great intro this morning into finding source code related to mom6/om3 builds.

@angus-g, I've just sent you an invite to the repo' (I couldn't add you as a reviewer I think until you've accepted but feel free to review if you wish.)

Note: I'm only looking for a review on this file: documentation/docs/pages/decoding_mom6.md. You can ignore the other changes.

---

Here's the rendered version:
https://decoding-access-om3--9.org.readthedocs.build/decoding_mom6/#how-do-i-find-out-which-version-of-mom6-i-am-currently-using

[chrisb13]

@atteggiani the lychee/link checker complained about a few re-directs and other minor looking things. I have a feeling most of those errors are ok, can I just ignore them?

Also it reports that the preview built:
https://decoding-access-om3--9.org.readthedocs.build/

But when I click on it I get: 500 Internal Server Error

[atteggiani]

@atteggiani the lychee/link checker complained about a few re-directs and other minor looking things. I have a feeling most of those errors are ok, can I just ignore them?

Also it reports that the preview built: https://decoding-access-om3--9.org.readthedocs.build/

But when I click on it I get: 500 Internal Server Error

There are 14 errors in total.

The redirects don't cause errors.

Some of the 404 errors are actually non-existent pages. I would control the related links in the referenced files.

The [ERROR] errors are all related to fragments not found (Cannot find fragment: ...). This means the link checker cannot find the part after the hash #... in the links (e.g., #eq:cont for the first link).
That syntax might work for some latex content but doesn't work on MkDocs.

To reference specific functions (or in general portions of the text), you should assign an HTML id to that portion (how to do this depends on the text you want to link to) and then link to that specific id using a fragment (e.g., #<id>).

For example I can assign the id eq1 to the first equation (that I want to link to) by adding {: #eq1 } after defining the equation text in the .md file (note this might not work as espected and I suggest reading https://python-markdown.github.io/extensions/attr_list/ and https://github.com/ACCESS-NRI/ACCESS-Hive-Docs?tab=readme-ov-file#styling-markdown-using-css for details). Then to reference to it in the same page I can use a link like [the first function](#eq1). From another page I would need to also include the page url: [the first function](/path/to/web/page/with/function#eq1).

So for this case, all link-checker failures should be fixed (As it's very often the case).

[chrisb13]

Thanks @atteggiani that's really helpful.

So I've fixed the reference ones (well, a hack for now -- e28278f) but I'm still a little confused by these four remaining ones:

Errors in /home/runner/work/decoding-om3/decoding-om3/docs_folder/AOMSS_Lecture_Notes/index.html

• [404] https://access-community-hub.github.io/decoding-om3/pages/AOMSS_Lecture_Notes/ | Rejected status code (this depends on your "accept" configuration): Not Found

Errors in /home/runner/work/decoding-om3/decoding-om3/docs_folder/decoding_mom6/index.html

• [404] https://access-community-hub.github.io/decoding-om3/pages/decoding_mom6/ | Rejected status code (this depends on your "accept" configuration): Not Found

Errors in /home/runner/work/decoding-om3/decoding-om3/docs_folder/index.html

• [404] https://access-community-hub.github.io/decoding-om3/pages/ | Rejected status code (this depends on your "accept" configuration): Not Found
  Error: R] https://docs.google.com/spreadsheets/d/1vk8m-oDRZChAFPnZ-HuF81YmiF7dkSXQkhZXekuj4fw/edit?gid=0#gid=0 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

Here's the details
https://github.com/ACCESS-Community-Hub/decoding-om3/actions/runs/21696727829/job/62568395470

[atteggiani]

So I've fixed the reference ones (well, a hack for now -- e28278f)

The solution is not to use code blocks with backticks (e.g., `...`), as this completely changes the rendering you want.
The solution is to properly format the code as it's supposed to be formatted for MkDocs: change all instances similar to [\[eq:momu\]](#eq:momu){reference-type="eqref" reference="eq:momu"} to something like [Eq:momu](#eq-momu) and when specifying the equation instead of writing $\label{eq:momu} add the id with an attribute list after the Latex code:

$\frac{\partial u}{\partial t}  + \frac{\partial uu}{\partial x} +  \frac{\partial vu}{\partial y} + \frac{\partial wu}{\partial z} - fv = g' \frac{\partial \eta_1}{\partial x} + \nu \nabla^2u$ {: #eq-momu }

This is not a Latex document, so not every Latex notation is supported. Latex references are not supported.
But I'm not an expert of the extension that supports Latex, so I don't know what you can/cannot do.

I'm still a little confused by these four remaining ones:

Errors in /home/runner/work/decoding-om3/decoding-om3/docs_folder/AOMSS_Lecture_Notes/index.html

• [404] https://access-community-hub.github.io/decoding-om3/pages/AOMSS_Lecture_Notes/ | Rejected status code (this depends on your "accept" configuration): Not Found

Errors in /home/runner/work/decoding-om3/decoding-om3/docs_folder/decoding_mom6/index.html

• [404] https://access-community-hub.github.io/decoding-om3/pages/decoding_mom6/ | Rejected status code (this depends on your "accept" configuration): Not Found

Errors in /home/runner/work/decoding-om3/decoding-om3/docs_folder/index.html

• [404] https://access-community-hub.github.io/decoding-om3/pages/ | Rejected status code (this depends on your "accept" configuration): Not Found
  Error: R] https://docs.google.com/spreadsheets/d/1vk8m-oDRZChAFPnZ-HuF81YmiF7dkSXQkhZXekuj4fw/edit?gid=0#gid=0 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

For these you need to update the hide_pages_url_segment.py hook:

https://github.com/ACCESS-Community-Hub/decoding-om3/blob/chrisb-building-navigating-mom6-source-codes/documentation/hooks/hide_pages_url_segment.py

# Change the URL segment for pages in MkDocs to hide the "/pages" prefix, so that pages inside the
# "pages" directory are served directly at the root URL.
from mkdocs.plugins import event_priority
@event_priority(-100)
def on_page_markdown(markdown, *, page, config, files):
    if page.file.url.startswith("pages/"):
        page.file.url = page.file.url.removeprefix("pages/")
        page.file.dest_uri = page.file.dest_uri.removeprefix("pages/")
        page.file.abs_dest_path = page.file.abs_dest_path.removeprefix("pages/")
+       page.canonical_url = config.site_url + page.file.url

And also change mkdocs.yaml:

decoding-om3/documentation/mkdocs.yml

Line 7 in 5ea94d7

site_url: !ENV [SITE_URL, "https://access-community-hub.github.io/decoding-om3/"]

- site_url: !ENV [SITE_URL, "https://access-community-hub.github.io/decoding-om3/"]
+ site_url: !ENV READTHEDOCS_CANONICAL_URL

[jbisits]

@chrisb13 I made some changes that were intended to be suggestions but I accidentally commiteed them sorry! Hopefully they are acceptable.

[chrisb13]

@chrisb13 I made some changes that were intended to be suggestions but I accidentally commiteed them sorry! Hopefully they are acceptable.

Awesome, all good on committing them directly (actually my preference for this kind of thing).

I'll fix up the links that Davide has helped me with, then merge.