Bare documentation infrastructure

[ccarouge]

Adds the bare infrastructure for the documentation based off the configs doc infrastructure.

This builds locally. @atteggiani Should we look at using GitHub pages or readthedocs for this one? The decision to go with one or the other hasn't been made but we may have some idea of where it is likely to get. We probably don't need to setup both now, just choose one. Information for RTD is in this PR.

[atteggiani]

I agree we shouldn't go with both.
As such, my preference would go to use RTD.
Some templates for additional files are in Documentation infra

[ccarouge]

We've got a build from the PR! (see the "More Details" from the action). https://cmip7-input--131.org.readthedocs.build/en/131/
I've added tech.accessnri as a maintainer on readthedocs so others can connect and manage stuff.

I think we are good to merge.

[ccarouge]

@atteggiani I've used the GitHub OAuth app for RTD because I'm not setup with the new GitHub App. So might need to migrate, soz.

[ccarouge]

@penguian not sure what to do about the failure of the pre-commit-check.

[atteggiani]

@atteggiani I've used the GitHub OAuth app for RTD because I'm not setup with the new GitHub App. So might need to migrate, soz.

No problem.
Actually the GitHub App has never been connected to ACCESS-NRI, so we've all always used RTD OAuth app (also from access-bot RTD account).
We might think about migrating after we finalise the RTD shenanigans.

Did you use your RTD account or access-bot to set this up?

[ccarouge]

@atteggiani:

Did you use your RTD account or access-bot to set this up?

Mine, but access-bot is a full maintainer. Actually, I forgot to give repository permissions to access-bot. So it is a maintainer, but it might not have the perms it needs to be fully functional.

[atteggiani]

Sounds good, thank you!

Actually, I forgot to give repository permissions to access-bot. So it is a maintainer, but it might not have the perms it needs to be fully functional.

Once the RTD project is setup, GitHub repo admin permissions are not needed to still be able to manage the RTD project.
I would not give access-bot admin permissions on the GitHub repo.

[penguian]

@atteggiani Do you know why the pre-commit checks are failing?

[penguian]

Checks are failing. Does this need to be fixed before approval?

[ccarouge]

@penguian The check-links failure might be because there are no build of the CMIP7-Input documentation yet (since we are putting the infrastructure together). There are preview builds but no "release" build.

For the pre-commit, I'm not sure which error it can't fix by itself. See the list here: https://github.com/ACCESS-NRI/CMIP7-Input/actions/runs/26386875899/job/77667255315?pr=131#step:4:158. It says it found 2 errors, 1 fixed and 1 remaining. But it does not say which one is fixed, and as far as I can tell, there are 3 failed, not 2... So if anyone knows how to read the report that would be useful.

One thing we likely can't fix is: could not determine a constructor for the tag '!ENV' in "documentation/mkdocs.yml", line 7, column 11 from the check_yaml hook. It would need a way to skip that file or line or something.

[atteggiani]

Yes, as Claire mentioned, the pre-commit checks should probably not include the mkdocs.yml file (I'm not even sure it should include yml file check at all).
I would also not include any txt files (e.g., requirements.txt).
I would probably only keep Python files in the checks.

The line too long error can be easily fixed by returning with a newline earlier in that line.

Also I am not sure which error was fixed and which not, but updating the hide_pages_url_segment.py and selecting only checks for .py files should hopefully fix all issues.