Writing documentation

Configuration schemas

If you add a new configuration schema, it is crucial that you add it to the list of schemas in the configuration Schemas reference.

1. Create a new file named reference/configuration/schemas/<filename>.md, where filename corresponds to filename.

2. Add the following contents to this file:

   # `<filename>.toml`: <Descriptive Title>
   
   :::{config:generate} <import path>.<of your>.<configurable class>
   :::
   

3. Add it to the index at reference/configuration/schemas/index.md.

4. To refer to your entire schema or a specific option, use the following Sphinx roles:

   • Referring to a schema. This looks like dummy.toml.

     {config:schema}`<filename>`
     

   • Referring to a specific option. This looks like dummy.toml::option_a.

     {config:field}`<filename>.<option>`
     

   • Referring to a specific option with a shortened reference. This looks like option_a.

     {config:field}`~<filename>.<option>`