Evaluate completeness of documentation about toml-f

[emilyviolet]

Hi @awvwgk, thanks for tagging me into this! I haven't worked on Fortran code in a while so didn't
realise you had the new RTD page. I will update the post accordingly.

Additionally, I'd like to volunteer to help with the documentation, rather than just complaining on
my blog. I've been meaning to do up some basic tutorials on toml-f for my day job, but just
haven't gotten around to it yet - would it be useful to collaborate with you on these, either now
or once you've made the changes in PRs #71 and #72?

[awvwgk]

Thanks for giving TOML Fortran a try and reaching out here.

For the docs I try to follow the Diátaxis framework, which partitions the documentation into sections depending on purpose and audience. If you have some useful snippets for doing certain tasks in TOML Fortran those could be added as a small recipe. We can use them as a starting point for the implementation of the additional get_value interfaces and try to improve the user experience for the respective tasks described in the docs.

Also, feel free to complain on missing documentation on the issue tracker, the discussion board or even the Fortran discourse. Especially a specific request makes it easier to create new guides or recipes to address the specific problem.

[emilyviolet]

Okay, I can do that. I have some time set aside tomorrow (Friday in Australia), so I'll see what I can do.

I think the existing tutorial is pretty much content-complete by the standards of the framework you linked - since we just want enough basic information to get someone started using toml-f. I think it could benefit from a little bit of expansion in some areas, such as including a sample TOML file alongside the reader function to make it easier to map specific calls to get_value to elements of the table, but aside from that it looks good for a 101-level guide.

I think the documentation could benefit from some "102-level" content that talks a little bit more about how the library's API is structured and what it does when you call it ("explanation" in the Diataxis framework). This is something I would've liked when I was starting out incorporating toml-f into a project, since without a clear understanding of why I need to do things a certain way I wasn't really able to come up with my own code beyond what I could find in the examples. The kind of content I'm thinking is information to help users build up their understanding of how the library works; something like "nested sections are their own child table, so you need to allocate and parse a new table before you can query them". What do you think?

I like the idea of writing small recipes/how-to guides for different common tasks, such as reading nested keys or dealing with arrays, then link to the relevant part of the explanation. I will start writing these up tomorrow and make a PR when I'm done with the first pass.

[awvwgk]

I started with a short recipe on iterating over subtables in #80. I will try to write a bit more on common use cases in configuration files and how to map them in TOML Fortran.

Maybe a complete walk-through for building a configuration file for an application, discussing advantages and disadvantages of certain data structures, would also be a good choice for a tutorial. I don't have something particular in mind yet for a topic, either package management or computational chemistry might be themes I would chose for such a guide.

[emilyviolet]

This sounds good to me! I'm biased towards computational chemistry as a tutorial theme because that's my field too, but this is a weak preference. I might have less time to spend on this over the coming weeks, but I'll see if I can gather some user feedback as I roll out the new version of my application (especially if you decide to go with a chemistry-themed tutorial).

[awvwgk]

This should be mostly covered now, I created separate issues for the generated docs (#83) and a more extensive tutorial (#84).