Make the default config table searchable in docs

The content of the old config.md was moved into config_no_table.md
with the include("config_table.jl") at the bottom removed.

Now, config_table.jl, creates the config.md by reading
config_no_table.md and copying the lines into it. Then,
it generates the pretty table and adds it to the end of the file.

This allows the table to be searchable, but it does not require users
to manually update the docs when the default config yaml is modified.

Fix formatting

Remove generated config.md from git index

.gitignore

@@ -19,8 +19,10 @@ deps/usr/
 deps/src/
 
 # Build artifacts for creating documentation generated by the Documenter package
+# and running docs/make.jl
 docs/build/
 docs/site/
+docs/src/config.md
 
 # File generated by Pkg, the package manager, based on a corresponding Project.toml
 # It records a fixed state of all packages used by the project. As such, it should not be

docs/make.jl

@@ -6,7 +6,7 @@ using DocumenterCitations
 
 disable_logging(Base.CoreLogging.Info) # Hide doctest's `@info` printing
 bib = CitationBibliography(joinpath(@__DIR__, "bibliography.bib"))
-
+include(joinpath(@__DIR__, "src", "config_table.jl"))
 doctest(ClimaAtmos; plugins = [bib])
 disable_logging(Base.CoreLogging.BelowMinLevel) # Re-enable all logging
 

docs/src/config.md → docs/src/config_no_table.md

@@ -5,7 +5,7 @@ In the file, you can set configuration arguments as `key: value` pairs to overri
 YAML parsing is fairly forgiving -- values will generally be parsed to the correct type.
 The only exception is true/false strings. These need quotes around them, or they will be parsed to `Bool`s.
 
-To start the model with a custom configuration, run: 
+To start the model with a custom configuration, run:
 
 `julia --project=examples examples/driver.jl --config_file <yaml>`
 
@@ -43,14 +43,14 @@ dt_save_state_to_disk: "10mins"
 toml: [toml/prognostic_edmfx.toml]
 ```
 
-Keys can also point to artifacts. As artifacts are folders, we specify both the artifact name, as we would from the REPL, and file to read from, separated by a `/`. For example, to drive a single 
-column model with an external forcing file from GCM output, we include the following lines in the 
+Keys can also point to artifacts. As artifacts are folders, we specify both the artifact name, as we would from the REPL, and file to read from, separated by a `/`. For example, to drive a single
+column model with an external forcing file from GCM output, we include the following lines in the
 configuration:
 ```
 insolation: "gcmdriven"
 external_forcing_file: artifact"cfsite_gcm_forcing"/HadGEM2-A_amip.2004-2008.07.nc
 ```
-To learn more about artifacts and how they're used in CliMA, visit [ClimaArtifacts.jl](https://github.com/CliMA/ClimaArtifacts). 
+To learn more about artifacts and how they're used in CliMA, visit [ClimaArtifacts.jl](https://github.com/CliMA/ClimaArtifacts).
 
 To add a new configuration argument/key, open `.buildkite/default_config.yml`.
 Add an entry with the following format:
@@ -65,6 +65,4 @@ See below for the full list of configuration arguments.
 
 
 # Default Configuration
-```@example
-include("config_table.jl");
-```
+

docs/src/config_table.jl

@@ -1,4 +1,6 @@
 const ca_dir = joinpath(@__DIR__, "..", "..")
+const output_file = joinpath(@__DIR__, "config.md")
+const input_file = joinpath(@__DIR__, "config_no_table.md")
 import YAML
 # Use OrderedCollections to preserve YAML order for docs
 import OrderedCollections: OrderedDict
@@ -16,16 +18,29 @@ function make_table_from_config_file(config_file, title)
     end
     data = hcat(config_names, config_types, config_helps)
     pretty_table(
+        String,
         data;
         title = title,
         header = ["Argument", "Type", "Description"],
         alignment = :l,
-        crop = :none,
+        backend = Val(:markdown),
     )
 end
 default_configs = joinpath(ca_dir, "config", "default_configs")
 default_config_file = joinpath(default_configs, "default_config.yml")
-
-make_table_from_config_file(default_config_file, "Default configuration")
+open(output_file, "w") do config_md
+    open(input_file) do f
+        while !eof(f)
+            s = readline(f)
+            write(config_md, s)
+            write(config_md, "\n")
+        end
+    end
+    table = make_table_from_config_file(
+        default_config_file,
+        "Default configuration",
+    )
+    write(config_md, table)
+end
 
 nothing