mllam/neural-lam

Structured documentation for Neural-LAM

Open

#61 opened on Jun 18, 2024

View on GitHub
 (32 comments) (0 reactions) (0 assignees)Python (276 forks)auto 404
documentationenhancementgood first issue

Repository metrics

Stars
 (282 stars)
PR merge metrics
 (PR metrics pending)

Description

As Neural-LAM grows and we make changes to it there is an increasing need for documentation. Already now the README is quite long, and some things are not that easy to find in it. I propose that we should set up a more robust and structured documentation solution. The idea of this issue is to start a discussion about how to do this.

When thinking about documentation for different open source python project, one that I really like is the pytorch geometric documentation. This uses Read the docs + Sphinx. In particular, you can create a documentation that contains both:

  1. Manually written tutorials, quickstart-guides, installation instructions, etc.
  2. A full API reference for all classes and functions in the codebase (descriptions + arguments + what is returned), generated directly from the docstrings in the python code.

I think having both of these is desirable, and think we could set up something like this for Neural-LAM.

I know that in weather-model-graphs you have these nice Jupyter books for documentation @leifdenby. Is there a way to do these things in those as well? In particular, is it possible to do the automatic reference generation from docstrings?

Contributor guide