create documentation

[isabellaascione]

This pull request includes initial demonstration to build documentation for the profsea-climate project.
Pull request related to #46

Website:
https://isabellaascione.github.io/ProFSea-tool/

The changes were made inside the profsea-climate branch and the documentation is deployed from profsea-climate branch.

Below is a summary of the changes made:

1. Documentation Source Updates:

Configured the Sphinx documentation build process using the Makefile and make.bat files.
Ensured the documentation builds successfully into HTML format under the html folder

2. Environment Configuration:

included environment.yml file with dependencies required for building the documentation, such as Sphinx and related extensions.

3. Generated Outputs:

Verified the generated HTML files, including:

• index.html
• development_guidelines.html
• user_guide.html
• references.html

It might be useful to discuss what structure would you like to have for the documentation. For the sake of the demonstration I added development_guidelines, user_guide, references but this can be changed / have subfolder structure if needed.

[Greg Munday (gregrmunday)]

Hi Isabella, could you please set this up to use the NumPy style docstrings formatting? I believe it requires using the napoleon package, but shouldn't be too difficult to set up.

[Greg Munday (gregrmunday)]

And as for theme - can we try this one out?

https://pydata-sphinx-theme.readthedocs.io/en/stable/

Both ESMValTool and Iris use this one. Looks modern and clean.

[isabellaascione]

Hi Greg Munday (@gregrmunday) , I have now added to the demonstrator of Sphinx documentation the use of NumPy style docstring formatting (using napoleon as you suggested). I changed the theme to PyData, and I also added docstrings to a python script spatial_projections.py as an example. I also demonstrate the use of Sphinx API rendering with spatial_projections.py.

Please note this is a demo , that is why I only edited spatial_projections.py docstrings. At the moment for what I understood in your latest email, I should wait for the main to be available to then apply this type of change more broadly.

one example of Sphinx API rendering is :

https://isabellaascione.github.io/ProFSea-tool/api_reference.html#module-profsea.spatial_projections

Summary:

This update is a demo/prototype to validate the documentation workflow (NumPy-style docstrings + Sphinx API rendering) before wider rollout. I am now waiting for confirmation on two points: 1. when the main branch is ready for me to apply the same approach, and 2. the required scope of docstrings (do you want just docstrings or you also want them rendered in the Sphinx pages) . For API rendering a selected scope is usually preferred first because it prioritizes user-facing/stable interfaces, keeps API docs clearer for users, and avoids exposing fast-changing internal helpers too early.

At a high level, the process is:

1. Add docstrings in the Python code.
2. Decide which modules/functions/classes should be user-visible in the API docs.
3. Explicitly include those items in the Sphinx API pages (autodoc/autosummary + toctree).

I would need to know at some point:

1. when the main is ready for me to fork and edit docstrings in python files, so I can apply the approach more broadly
2. If you want the Sphinx API rendering and , which python scripts would you like to see rendered

[Greg Munday (gregrmunday)]

Thanks isabellaascione, this looks awesome!!

I think we should talk about which scope we want to render in the docs in our next meeting, and try to work out what the usual done-thing is. My feeling is that any method without an _ in front should be included in the API docs, i.e. any 'public' functions? Keen to hear your thoughts on this though.

Two questions to answer back to your two questions:

• Is it possible to lift this PR onto profsea-climate-v2? All the docstrings in there should be in the correct format, and then when it gets merged into main then it should be a smoother process to merge the documentation too, rather than you having to start from scratch.
• Is it possible to render tutorial notebooks nicely in the documentation, on their own "Tutorials" or "User Guide" tab or something? I know there's ways to do code snippets, which I'd like to experiment with a bit, but again it would be useful to have this based on a more current working version of the code because the API has changed a lot in profsea-climate-v2 compared to profsea-climate

[isabellaascione]

Hi related to the question:

Is it possible to lift this PR onto profsea-climate-v2? on Friday I updated my fork to have the changes in the the profsea-climate-v2 branch, but now I cannot see any more that branch in the main repository I think. The changes to the profsea-climate-v2 branch are visible in the link below where I have updated the workflows and made some changes to the docstrings:

The changes are :

isabellaascione/ProFSea-tool@edb2eb0...bb11a4c

Related to the question "Is it possible to render tutorial notebooks nicely in the documentation, on their own "Tutorials" or "User Guide" tab or something? "
It is possible to render the tutorials, in sphinx, and for this to work the notebooks need to be seen by sphinx. It will make sense to put the notebook under the docs folder.

The results of the changes I made are visible on the updated webpage:

https://isabellaascione.github.io/ProFSea-tool/

you can see the updated API reference pages in the corresponding section of the documentation

I will be happy to discuss as well with Jennifer Weeks (@mo-jenniferweeks) Hemant Khatri (@hmkhatri)

thanks

[Greg Munday (gregrmunday)]

Thanks isabellaascione, looks good! Sorry, things are moving quickly - is it possible now to please base this off the ProFSea v3 branch (#65)?

This branch will be merged into main and the docs then deployed when merged, and so we want to have the docs all set up to go. During the v3 PR we can then round out whatever other documentation we need and work on making a landing page, user guide, etc.

[Greg Munday (gregrmunday)]

I guess when I mean base off, I mean just actually move the docs into the v3 code!