Merge pull request #3402 from CliMA/tr/make-default-config-table-sear…

…chable

Make the default config table searchable in docs

.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