Export dedent and apply it to contract documentation strings.

tanaylab · Apr 1, 2024 · 3d267ff · 3d267ff
1 parent d76945c
commit 3d267ff
Show file tree

Hide file tree

Showing 9 changed files with 97 additions and 22 deletions.
diff --git a/docs/v0.1.0/.documenter-siteinfo.json b/docs/v0.1.0/.documenter-siteinfo.json
@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-03-29T23:41:20","documenter_version":"1.3.0"}}
+{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-04-01T13:53:18","documenter_version":"1.3.0"}}
diff --git a/docs/v0.1.0/generic.html b/docs/v0.1.0/generic.html
@@ -160,6 +160,12 @@
 </a>
 </li>
 <li>
+<a class="tocitem" href="#Strings">
+<span>Strings
+</span>
+</a>
+</li>
+<li>
 <a class="tocitem" href="#Index">
 <span>Index
 </span>
@@ -429,6 +435,38 @@ <h2 id="Unions">
 </div>
 </section>
 </article>
+<h2 id="Strings">
+<a class="docs-heading-anchor" href="#Strings">Strings
+</a>
+<a id="Strings-1">
+</a>
+<a class="docs-heading-anchor-permalink" href="#Strings" title="Permalink">
+</a>
+</h2>
+<article class="docstring">
+<header>
+<a class="docstring-article-toggle-button fa-solid fa-chevron-down" href="javascript:;" title="Collapse docstring">
+</a>
+<a class="docstring-binding" id="Daf.Generic.dedent" href="#Daf.Generic.dedent">
+<code>Daf.Generic.dedent
+</code>
+</a> — 
+<span class="docstring-category">Function
+</span>
+</header>
+<section>
+<div>
+<pre>
+<code class="language-julia hljs">function dedent(string::AbstractString; indent::AbstractString = &quot;&quot;)::String
+</code>
+</pre>
+<p>Given a possibly multi-line string with a common indentation in each line, strip this indentation from all lines, and replace it with 
+<code>indent
+</code>. Will also strip any initial and/or final line breaks.
+</p>
+</div>
+</section>
+</article>
 <h2 id="Index">
 <a class="docs-heading-anchor" href="#Index">Index
 </a>
@@ -463,6 +501,12 @@ <h2 id="Index">
 </a>
 </li>
 <li>
+<a href="generic.html#Daf.Generic.dedent">
+<code>Daf.Generic.dedent
+</code>
+</a>
+</li>
+<li>
 <a href="generic.html#Daf.Generic.handle_abnormal">
 <code>Daf.Generic.handle_abnormal
 </code>

diff --git a/docs/v0.1.0/index.html b/docs/v0.1.0/index.html
@@ -1716,6 +1716,12 @@ <h1 id="Index">
 </a>
 </li>
 <li>
+<a href="generic.html#Daf.Generic.dedent">
+<code>Daf.Generic.dedent
+</code>
+</a>
+</li>
+<li>
 <a href="generic.html#Daf.Generic.handle_abnormal">
 <code>Daf.Generic.handle_abnormal
 </code>

diff --git a/docs/v0.1.0/objects.inv b/docs/v0.1.0/objects.inv
diff --git a/docs/v0.1.0/search_index.js b/docs/v0.1.0/search_index.js
diff --git a/src/contracts.jl b/src/contracts.jl
@@ -7,6 +7,7 @@ export Contract
 export ContractAxes
 export ContractData
 export ContractExpectation
+export dedent
 export GuaranteedOutput
 export OptionalInput
 export OptionalOutput
@@ -313,7 +314,7 @@ function scalar_documentation(contract::Contract, buffer::IOBuffer; is_output::B
                     println(buffer, "### Scalars")
                 end
                 println(buffer)
-                println(buffer, "**$(name)**::$(data_type) ($(short(expectation))): $(description)")
+                println(buffer, "**$(name)**::$(data_type) ($(short(expectation))): $(dedent(description))")
             end
         end
     end
@@ -334,7 +335,7 @@ function axes_documentation(contract::Contract, buffer::IOBuffer; is_output::Boo
                     println(buffer, "### Axes")
                 end
                 println(buffer)
-                println(buffer, "**$(name)** ($(short(expectation))): $(description)")
+                println(buffer, "**$(name)** ($(short(expectation))): $(dedent(description))")
             end
         end
     end
@@ -357,7 +358,10 @@ function vectors_documentation(contract::Contract, buffer::IOBuffer; is_output::
                         println(buffer, "### Vectors")
                     end
                     println(buffer)
-                    println(buffer, "**$(axis_name) @ $(name)**::$(data_type) ($(short(expectation))): $(description)")
+                    println(
+                        buffer,
+                        "**$(axis_name) @ $(name)**::$(data_type) ($(short(expectation))): $(dedent(description))",
+                    )
                 end
             end
         end
@@ -383,7 +387,7 @@ function matrices_documentation(contract::Contract, buffer::IOBuffer; is_output:
                     println(buffer)
                     println(
                         buffer,
-                        "**$(rows_axis_name), $(columns_axis_name) @ $(name)**::$(data_type) ($(short(expectation))): $(description)",
+                        "**$(rows_axis_name), $(columns_axis_name) @ $(name)**::$(data_type) ($(short(expectation))): $(dedent(description))",
                     )
                 end
             end

diff --git a/src/generic.jl b/src/generic.jl
@@ -7,6 +7,7 @@ code, explicitly write `using Daf.Generic`.
 """
 module Generic
 
+export dedent
 export ErrorHandler
 export handle_abnormal
 export AbnormalHandler
@@ -67,4 +68,34 @@ statistics to represent missing (that is, unknown) data. It is only provided her
 """
 Unsure = Union{T, Missing} where {T}
 
+"""
+    function dedent(string::AbstractString; indent::AbstractString = "")::String
+
+Given a possibly multi-line string with a common indentation in each line, strip this indentation from all lines, and
+replace it with `indent`. Will also strip any initial and/or final line breaks.
+"""
+function dedent(string::AbstractString; indent::AbstractString = "")::String
+    lines = split(string, "\n")
+    while !isempty(lines) && isempty(lines[1])
+        @views lines = lines[2:end]  # untested
+    end
+    while !isempty(lines) && isempty(lines[end])
+        @views lines = lines[1:(end - 1)]
+    end
+
+    first_non_space = nothing
+    for line in lines
+        line_non_space = findfirst(character -> character != ' ', line)
+        if first_non_space == nothing || (line_non_space != nothing && line_non_space < first_non_space)
+            first_non_space = line_non_space
+        end
+    end
+
+    if first_non_space == nothing
+        return indent * string  # untested NOJET
+    else
+        return join([indent * line[first_non_space:end] for line in lines], "\n")  # NOJET
+    end
+end
+
 end  # module
diff --git a/src/generic.md b/src/generic.md
@@ -33,6 +33,12 @@ Daf.Generic.Maybe
 Daf.Generic.Unsure
 ```
 
+## Strings
+
+```@docs
+Daf.Generic.dedent
+```
+
 ## Index
 
 ```@index

diff --git a/test/runtests.jl b/test/runtests.jl
@@ -23,22 +23,6 @@ Random.seed!(123456)
 inefficient_action_handler(ErrorHandler)
 abort_on_first_failure(true)
 
-function dedent(string::AbstractString)::String
-    lines = split(string, "\n")[1:(end - 1)]
-    first_non_space = nothing
-    for line in lines
-        line_non_space = findfirst(character -> character != ' ', line)
-        if first_non_space == nothing || (line_non_space != nothing && line_non_space < first_non_space)
-            first_non_space = line_non_space
-        end
-    end
-    if first_non_space == nothing
-        return string  # untested
-    else
-        return join([line[first_non_space:end] for line in lines], "\n")
-    end
-end
-
 function with_unwrapping_exceptions(action::Function)::Any
     try
         return action()