Write proper documentation

[luator]

The documentation is currently pretty poor. There is already some stuff in docs/ but so far it is not much more than an (incomplete!) list of available settings. This should be extended to contain

• [ ] High-level overview what cluster_utils is and how it works.
• [ ] Complete list of settings (probably also a bit better structured than at the moment). This depends on #41.
• [ ] Description of the different modes (hp_optimization vs grid_search) with usage examples.
• [x] Description of the different options to provide an environment (venv/conda/apptainer).
• [ ] Description of the cluster-system-specific things.
• [ ] Proper description of what needs to be called in the job script.
• [x] Describe how exit_for_resume works.
• [ ] probably more...
• [x] ...and should be hosted somewhere online.

[luator]

Honestly I think the effort is only worth it if the documentation is accessible online in some way. Most people will not build the docs locally just to quickly open them.

Fully agree. I actually wanted to add this as a point in the list but obviously forgot... Added now.

What I think would be (additionally) great is if help is already provided through running the package itself, e.g. help strings for the different options.

That would be really cool but we would need to think about how to implement that in a maintainable way (ideally in a way that we don't have to duplicate descriptions in the rendered docs and the in-app-help).

By Felix Widmaier on 2023-11-28T16:47:47 (imported from GitLab)

[luator]

Honestly I think the effort is only worth it if the documentation is accessible online in some way. Most people will not build the docs locally just to quickly open them.

What I think would be (additionally) great is if help is already provided through running the package itself, e.g. help strings for the different options.

By Maximilian Seitzer on 2023-11-28T16:47:47 (imported from GitLab)

[luator]

By coincidence I just stumbled over the diátaxis approach for structuring technical documentation. It basically suggests to organise documentation in four distinct types of articles: tutorials, how-to guides, explanations and references. It sounds quite nice to me, so I suggest that we give it a try when writing/structuring the documentation.

By Felix Widmaier on 2024-01-08T12:20:39 (imported from GitLab)

[luator]

Btw, I asked the IT people some time ago regarding a place to host the documentation. Unfortunately the Pages feature is not available in our GitLab instance, so we would need to put in somewhere else (which likely takes a bit more effort to set up). However, I assume we will anyway move the code to either GitHub or a university server in the near future, so maybe it makes more sense to wait until after this move before we decide on a solution?

By Felix Widmaier on 2023-12-13T09:54:54 (imported from GitLab)

[luator]

marked the checklist item Description of the different options to provide an environment (venv/conda/apptainer). as completed

By Felix Widmaier on 2023-12-13T09:55:19 (imported from GitLab)

[luator]

For the record, documentation is now hosted on GitHub Pages of this repo.

[luator]

Update: I moved to Read the Docs yesterday, as this will allow us to much more easily host separate versions of the documentation for the different PyPI releases.