Configs documentation plan #908
Comments
|
Hi atteggiani, Thanks for the detailed summary of some of the upcoming considerations regarding the access hive "config docs". Really exciting and helpful to better understand some of the technical issues ahead! Some further thoughts below.
Sounds good
Yes, our starting point will be but likely also (@blimlim @ccarouge) However, there is a related interest in creating some "model docs" for WOMBAT (@pearseb @dougiesquire), this will use
@aekiss, made a good point about this. Ideally it would be more flexible. This is because we will likely want to update the docs at times when we are not updating the configs (e.g. fixing typos, user contributions etc). As we discussed @atteggiani this afternoon, it's a little tricky given that releases occur for specific config's. We'll need to think more about this.
As the above suggestion, yes, we'll want something like this but will need to think carefully about how we release a 'zenodo version'
Sounds perfect!
Ok but I think it would be possible to do if we use a separate forwarding service? My reading of this* is that it might be possible with a "Project site", will look more into it. *"Project sites, whether owned by an organization or a personal account, are unlimited."
As we discussed @atteggiani this afternoon, we'll keep thinking about possible solutions. |
|
It does not seem to be known but readthedocs is compatible with mkdocs. That is what we are using for the CABLE docs. We have chosen to go this route because of the versioning. Readthedocs is built to support versioning based on tags so it was the easiest route for us. A few links to see how it works and is setup if you are interested: 
|
|
After reading the limitations outlined in the first message, it looks it might be worth looking at readthedocs. Changing the whole setup is particularly annoying and I wouldn't recommend doing it without a good reason. From a coarse read of readthedocs doc and my poor understanding of websites, however, it seems readthedocs would solve some of the problems mentioned. |
|
Thank you for the useful information @ccarouge! Does readthedocs provide automatic hosting as well? How does it work? I agree, mkdocs, mkdocs-material and readthedocs can be completely viable options and they have multiple plugins/extensions already available to handle most of our use cases (versioning from tags, documentation from code, etc.). I think trying to standardize the framework used (for new docs) makes sense so whoever is working on that project/doc has an "easier" pathway forward because multiple things can be copied from other repos. In this specific case, for the versioning, what you do with CABLE can be achieved by using both readthedocs or mkdocs-material (I haven't tested but according to the documentation it should be too hard). |
|
I second just using readthedocs. Does everything really need to be part of |
Domains can be changed even for readthedocs (in case we want), so I don't see any issue with that.
|
What's your thinking there @dougiesquire? It is just the set up faff? Unsurprising at this point I suppose.. I'm in favour of using mkdoc. I think being close to the access-hive makes the user feel like there is fewer doc systems. So having a similar look and feel is useful, as is one team helping manage the same system. And my impression is that we have similar challenges in both systems. Davide and I have made some offline progress on the deployment issue so it's not as tricky as above posts appear.
Out of scope (here) but I think this is an important one and it would be great to see that addressed. Let's catch up on point 2. |
As @ccarouge points out, readthedocs can be used with mkdocs. My thinking is the same as @ccarouge's: some of the difficulties flagged in an earlier post should be easily handled with readthedocs. I'm quite possibly misunderstanding/oversimplifying something here, but the theme is something that is easy to change later. It would be a shame for details around how the docs look to get in the way of getting docs hosted somewhere. |
Again, I'm probably misunderstanding the issue, but is this necessary if separate docs are hosted on separate websites? |
Yes I completely agree. My point 1 here can definitely be addressed at a later time and should not block the development/hosting of the documentation. If readthedocs supports mkdocs and solves the hosting problems, I don't see reasons not to go with it. |
As above I'm not sure I understand the issue here. Can the docs for each repo (e.g. cable, wombat, om3-configs etc) be hosted and versioned independently and then linked to from access hive docs? |
|
For Cable and Wombat yes. For om3-configs (and any model config repo), there are multiple experiment configurations within the same repo, each versioned separately. As an example, for ACCESS-ESM1.5-configs, there are:
Similar patterns exist for ACCESS-OM2 and (in the future) for ACCESS-OM3. Will in general the model config experiment configurations be updated at the same time? If that is the case, then there is a solution (but not as simple as Wombat or Cable), because the documentation version can be attributed to the latest experiment config version number: for example, documentation version If the experiment configuration versioning is independent: for example the latest |
Background
This issue is a starting point for a discussion and future planning on ACCESS-NRI documentation websites.
Currently, the only ACCESS-NRI documentation website is the Hive Docs (this repo).
However, as a topic started by @chrisb13, there is the need to have other websites for technical documentation related to various model config repos (an example is the ACCESS-OM3-configs repo, but this could be applied to any ACCESS-NRI model config repo).
Model config repo documentation will be referred to as config docs below.
Documentation framework
It was decided that, for consistency and to simplify development, the framework used to develop all documentation websites will be mkdocs, specifically the mkdocs-material theme (which is the one used for the Hive Docs website).
Requirements for config docs
docsfolder, and therefore will be versioned together with model config repo versioning structure (usinggittags). In this sense,config docs versionandmodel config versionrefer to the same version and mean the same thing.latestversion as default, but users should be able to select a past config docs versionWebsite build/Layout/Design
We should aim for a consistent layout/design across websites (this has been already a point of discussion within the Hive Docs team).
For the Documentation websites (Hive Docs, config docs), since the plan is to use
mkdocs-material, I think the best solution is to have a custommkdocs-materialbuild that is used to build all documentation websites. This common build would contain the basic website structure and layouts that are shared across all doc websites, with the possibility for each of them to still have website-specific design.Deployment/Domain (URL)
We are currently using GitHub pages to deploy the Hive Docs. Currently it works great and we don't have to pay a hosting service (we only pay the domain - https://access-hive.org.au/).
Domain
GitHub pages doesn't allow multiple sub-domains (for example
configs.access-hive.auanddocs.access-hive.au) for the same user/organization.What we can have is multiple sub-pages (e.g.:
access-hive.au/configs/...,access-hive.au/docs/..., as it already happens for the Hive Docs development website and PR-previews websites).I think this is our only option if we want to deploy the websites through GitHub pages.
Deployment through GitHub pages
Deployment for different builds (different
mkdocs.yaml) under sub-pages of the same root domain is possible but there are drawbacks that need to be discussed. Some relevant ones are detailed in the paragraphs below.GitHub Pages size limitations
GitHub pages have limitations. In particular:
This is not a strict rule as the current Hive Docs website, including the main website, development website and each PR-preview websites, are about 2GB now but the deployments succeeds, even though there is a warning message.
Even with optimisations implemented and with config docs websites that should not be bigger than 20-30 MB each, if we end up having multiple websites is likely we reach a point where the deployment will fail. Therefore, it is something we need to discuss.
Website deployment concurrency
For purpose of deployment, all documentation websites (Hive Docs + config docs) should be seen as one single website (composed by multiple more-or-less-separated sub-pages): for any sub-page to be re-deployed the whole website needs to be re-deployed. This also includes cases when PR-previews are deployed (basically each deployment, regardless how it was triggered, deploys the entire website).
However, only ONE single website is present at the same time by accessing the root URL (and any sub-pages), that corresponds to the latest deployed instance.
With multiple unrelated docs that need to be joined together for a single deployment, this generates concurrency problems (I will not go over all the details here but I'll be happy to explain further on this).
This point also needs a discussion.
Summary
I think having technical documentation for the model configs is very important.
To achieve a good user-experience and ensure seamless and simple (enough) documentation development process, I think addressing the points above is crucial and a proper discussion/planning is necessary.
The text was updated successfully, but these errors were encountered: