From 0251c91d7a6648b0b9601845d70d3f31d70e03cd Mon Sep 17 00:00:00 2001
From: imreddyTeja <treddy0205@gmail.com>
Date: Fri, 25 Oct 2024 15:00:07 -0700
Subject: [PATCH] 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                                 |  2 ++
 docs/make.jl                               |  2 +-
 docs/src/{config.md => config_no_table.md} | 12 +++++-------
 docs/src/config_table.jl                   | 21 ++++++++++++++++++---
 4 files changed, 26 insertions(+), 11 deletions(-)
 rename docs/src/{config.md => config_no_table.md} (93%)

diff --git a/.gitignore b/.gitignore
index f7ba7f5fd5..4cf65a220c 100644
--- a/.gitignore
+++ b/.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
diff --git a/docs/make.jl b/docs/make.jl
index 8f7ef2ed8d..5de759d61c 100644
--- a/docs/make.jl
+++ b/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
 
diff --git a/docs/src/config.md b/docs/src/config_no_table.md
similarity index 93%
rename from docs/src/config.md
rename to docs/src/config_no_table.md
index b73f61c8e5..05b532749d 100644
--- a/docs/src/config.md
+++ b/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");
-```
+
diff --git a/docs/src/config_table.jl b/docs/src/config_table.jl
index 2203b1300c..b9c247c486 100644
--- a/docs/src/config_table.jl
+++ b/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