Polish documentation

[SeanBryan51]

A few improvements that can be made to the documentation:

• Add acknowledgements section in documentation
• PyOpenSci python package guidelines:
  • Minimal developer guide: should include dev environment setup (linting, formatting, type checking), running tests, building documentation locally, etc
  • Need docs for API (e.g. the command line interface)
  • Repository files (CONTRIBUTING.md, LICENSE, COPYRIGHT)
• Improve readability of config.yaml documentation #140

[ccarouge]

About the API docs, since Sphinx can do that automatically using the Python docstrings, would it make sense to move the documentation to .rst and Sphinx? Or is the API small enough it isn't worth it?

I'm not sure I understand about the nested config options in config.yaml. I can't see a difference between our doc and the example link. Or do you mean to add an example for each nested option instead of one at the end?
I am wondering though if it would be worth limiting the table of contents to show the top option only (fluxsite but not the nested options).

[SeanBryan51]

About the API docs, since Sphinx can do that automatically using the Python docstrings, would it make sense to move the documentation to .rst and Sphinx? Or is the API small enough it isn't worth it?

I think docstrings won't actually be useful to us since the API for benchcab is really a command line interface. But it might be an idea for the future if we want to expose a python API? For the API documentation for the CLI, I had something like the GitHub CLI documentation in mind.

Yes I think an example for each option would help, especially for the options that are three levels deep as it is hard to tell from the reader if these options have a nested structure.

I don't really mind if the table of contents does not show all the options, but I want to keep the permanent links for each option so we can easily refer to specific options by sharing a link.

[ccarouge]

I agree the API is only the command line interface. But it would be great if we could use something that takes the documentation from the code and presents it on a nice web page. So we don't have 2 versions of the documentation: in the code, in the --help message and on the web. I was going to say it isn't possible with mkdocs, but I was so wrong: mkautodoc. It might be worth organising the documentation with this for the API.

I have made a start about config.yaml documentation, mainly because I needed to see it to know if that would be better or not. I've now opened a draft pull request so you can see what it could look like: #137

[tammasloughran]

On this page, I wanted to know more about the forty-two-site-test and the five-site-test. But the links to modelevalutation.org return a "page not found" page.

What where these intended to link to?

[SeanBryan51]

@tammasloughran the links should point to the respective experiments on modelevaluation.org, but you will need to be logged in for the links to work.

[tammasloughran]

I am :), still no go. Maybe they aren't shared with me?

[ccarouge]

Sorry @tammasloughran . We have put the wrong link in the documentation. It's the link to our own workspace for testing and development. We will update in the doc. In the mean time, these links should work for you:

• forty-two sites
• five sites
  All the experiments in benchcab are under the benchcab-evaluation workspace if you want to find them directly.