Automatic *usage* documentation

[Fons van der Plas]

Configrations.jl makes it really for me, as a package author, to add the following to my package:

• Passing configurations through my progra
• Reading configurations from a TOML file
• Accepting configurations from keyword arguments

I get all of this with almost zero work, the only thing I do is specify the 'schema' of my configurations! Awesome!!

What is still missing, and what could also be given for free, is:

1. Documentation for users of my package on how to configure my program
2. List of possible keyword arguments
3. Schema of the TOML file
4. Example TOML file demonstrating possible options, already filled in with default values

I.e. I have written the schema of my configuration, but I still need to explain to my users how to write a TOML file and/or what the possible keywords are. The documentation of Configurations.jl is only targeted to me (package author), it is too technical for my users.

---

It would be great if there was some unified documentation on how to use a package that is configured using Configurations.jl. Even better would be if this were automatically generated, like in my ideas above!

[Fons van der Plas]

I implemented 2 and 4 from my issue in PlutoSliderServer.jl: it might be reusable!

Automatic TOML file: https://github.com/JuliaPluto/PlutoSliderServer.jl/blob/29d9f5b03509036c938e199e7d6f8863a126f53b/src/PlutoSliderServer.jl#L45-L61
Automatic list of keyword arguments: https://github.com/JuliaPluto/PlutoSliderServer.jl/blob/29d9f5b03509036c938e199e7d6f8863a126f53b/src/PlutoSliderServer.jl#L103

Magic to make it work: https://github.com/JuliaPluto/PlutoSliderServer.jl/blob/main/src/ConfigurationDocs.jl

[Xiu-zhe (Roger) Luo]

Hi @fonsp thanks for the feedback, this is very helpful!

Documentation for users of my package on how to configure my program

I thought about this before, and yes, if we look at other similar packages in other languages, they can generate a standard schema specification such as OpenAPI or JSON schema which can be further rendered as HTML documentations, is this something you would like to have?

List of possible keyword arguments

Currently we only report this when user input a wrong keyword arguments, I'm not sure about where to list the keyword arguments, you mean some kind of Documenter plugin? can you elaborate about this?

Schema of the TOML file

there are some standards for JSON schema and seems to be widely adopted (as well as OpenAPI with YAML), but I'm not sure about TOML, I searched about bit but only found toml-lang/toml#792 thus I'm not sure what format should we generate to?

Example TOML file demonstrating possible options, already filled in with default values

I think for those already with default values, this is fairly easy (just use include_defaults=true on the object with default values), but for optional fields, in Julia we use nothing as default value, and in TOML we are expected to not specify that field, so we need to be able to generate a comment for the TOML file, e.g

[person]
name = "Roger"
# age = <int>

where field gender in Julia is like

struct Person
    name::String = "Roger"
    gender::Maybe{Int} = nothing
end

This is however limited by the TOML parser, so we probably need to write our own lowering pass to TOML to resolve this.