How do i create a documentation page in https://metoffice.github.io/lfric_apps/

[Alan J Hewitt (alanjhewitt)]

I have developed a proper API between radaer and lfric_apps which is under review.

I have a 360 word document which gives a summary of the API along with design principles, description of the elements of the interface, and a list of what has been implemented and what remains to be implemented.

Its pretty short and is all text, so it should be fairly easy to change to markdown.

My document is not easily accessible, so I would like to document it somewhere in https://metoffice.github.io/lfric_apps/

However, I could not find the documentation page describing how to make other documentation pages.
Could someone point me to this please?

[Andrew Coughtrie (andrewcoughtrie)]

Hi Alan, only part of that sounds like it should be put in the LFRic Apps documentation (the summary of the API) the rest sounds like it is more design docs that are being used during development which would generally go elsewhere. Who is your target audience for design parts of your doc?

[Andrew Coughtrie (andrewcoughtrie)]

Yes you will need to add something (possibly a new rst file) to either the user_guide section and/or the science_guide sections of the documentation. In terms of formatting, guidance can be found here and how to write restructured text Sphinx documentation is available in many places on the internet.

[Alan J Hewitt (alanjhewitt)]

I put together some .rst files in a branch today. Is there a guide to building them, so I can see if it works correctly?

[Jenny Hickson (jennyhickson)]

The documentation pages in the working practices should give you steps for testing your documentation. Cheers

https://metoffice.github.io/simulation-systems/Development/sphinx_docs.html

[Yaswant Pradhan (yaswant)]

I put together some .rst files in a branch today. Is there a guide to building them, so I can see if it works correctly?

Please see documentation/README

cd documentation
python3.12 -m venv .venv
.venv/bin/pip install .

# Activate the environment:
source .venv/bin/activate

# Check rst integrity
make lint

# Build and Deploy
make clean deploy

The built docs should appear in your ~/public_html so you could browse them via https://wwwspice/~alan.j.hewitt/lfric_apps/<your-branch-name>/html/

[Andrew Coughtrie (andrewcoughtrie)]

Sphinx and all required dependencies are already installed as part of the lfric software stack on AZSpice.

[Alan J Hewitt (alanjhewitt)]

This sequence of commands allowed me to build the documentation

lfric_apps]$ cd documentation/
documentation]$ ml use ~lfricadmin/lmod
note that the above command makes modules available in azure spice
documentation]$ module load lfric
documentation]$ make clean html
lots of print to screen
The HTML pages are in build/html.
documentation]$ firefox build/html/index.html &

the final command opens the built documentation in firefox

I ran into problems with building using .venv yesterday, I could speak to Yaswant Pradhan (@yaswant) offline. I suspect i didnt have the correct modules loaded.

[Yaswant Pradhan (yaswant)]

In order to work with virtual env, ensure that you:

• have permission to install packages from PyPi or MetOffice Artifactory (on Met Office network you need Artifactory credentials in .netrc file
• have the latest version of lfric_apps documentation (the project config pyproject.toml, and Makefile update for documentation went in July 22)

[Yaswant Pradhan (yaswant)]

Alan J Hewitt (@alanjhewitt) I just had just finished reviewing your linked UKCA-Apps PRs, and to me it feels like the new API related documentation should really go in UKCA unless I've completely misunderstood what document change you were proposing.

[Alan J Hewitt (alanjhewitt)]

Mohit Dalvi (@mcdalvi) Luke Abraham (@theabro) Rob Waters (@RobWatersMet)

Hi Yash, the plan was to have the main RADAER documentation in the UKCA repository. This would cover all of the functionality and user settings. Currently, this description needs to be migrated from Chapter 15 of UMDP084 https://code.metoffice.gov.uk/doc/um/latest/papers/umdp_084.pdf .

We also want a very minor description of the interface of LFRic to RADAER (in the lfric repo) and UM to RADAER (in the UM repo). There is less room for confusion if the interface description is outside of UKCA. We separately need to put an interface description to the main UKCA code, which already has three parent models (UM, LFRic_apps, NAME).

We have not made any progress so far with migrating the UMDP084 documentation from LaTeX to markdown. We have however been discussing ideas for how to migrate the documentation (also with Mark Richardson but i dont have his GitHub handle). It looks like MichaelWhitall may have a tool that worked for other UM documentation pages. We will discuss again at the next UKCA code management group and hopefully we will have identified who will work on this.

Kind regards,

Alan