Merge branch 'master' into 654-new-ramps

docs/Project.toml

@@ -1,3 +1,5 @@
 [deps]
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 SpineOpt = "0d8fc150-4032-4b6e-9540-20efcb304861"

src/util/docs_utils.jl → docs/docs_utils.jl

@@ -16,6 +16,35 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #############################################################################
+using CSV
+using DataFrames
+
+function write_documentation_sets_variables(mathpath)
+    variables = DataFrame(CSV.File(joinpath(mathpath, "variables.csv")))
+    variables.variable_name_latex = replace.(variables.variable_name, r"_" => "\\_")
+    variables.variable_name_latex .= "``v_{" .* variables.variable_name_latex .* "} ``"
+    variables.indices .= replace.(variables.indices, r"_" => "\\_")
+    variable_string = "# Variables \n"
+    for i in 1:size(variables, 1)
+        variable_string = string(variable_string, "## `$(variables.variable_name[i])` \n\n")
+        variable_string = string(variable_string, " > **Math symbol:** $(variables.variable_name_latex[i]) \n\n")
+        variable_string = string(variable_string, " > **Indices:** $(variables.index[i]) \n\n")
+        variable_string = string(variable_string, " > **Indices function:** $(variables.indices[i]) \n\n")
+        variable_string = string(variable_string, "$(variables.description[i]) \n\n")
+    end
+    sets = dropmissing(DataFrame(CSV.File(joinpath(mathpath, "sets.csv"))))
+    set_string = "# Sets \n"
+    for i in 1:size(sets, 1)
+            set_string = string(set_string, "## `$(sets.indices[i])` \n\n")
+            set_string = string(set_string, "$(sets.Description[i]) \n\n")
+    end
+    open(joinpath(mathpath, "variables.md"), "w") do io
+        write(io, variable_string)
+    end
+    open(joinpath(mathpath, "sets.md"), "w") do io
+        write(io, set_string)
+    end
+end
 
 """
     initialize_concept_dictionary(template::Dict; translation::Dict=Dict())
@@ -352,31 +381,29 @@ end
 """
     alldocstrings(m)
 
-Return all docstrings from the provided module m as a dictionary.
+A Dict mapping function name to its docstring for given Module.
 """
 function alldocstrings(m)
-    #allbindings(m) = [ [y[2].data[:binding] for y in x[2].docs] for x in Base.eval(m,Base.Docs.META) ]
-    bindings = []
-    for x in Base.eval(m,Base.Docs.META)
-        for y in x[2].docs
-            push!(bindings,[y[2].data[:binding]])
-        end
-    end
     alldocs = Dict()
-    for binding in bindings
-        dockey = split(string(binding[1]),".")[2]
-        docvalue = Base.Docs.doc(binding[1])
-        alldocs[dockey] = docvalue
+    for multidoc in values(Base.eval(m, Base.Docs.META))
+        for doc_str in values(multidoc.docs)
+            binding = doc_str.data[:binding]
+            key = split(string(binding), ".")[2]
+            value = Base.Docs.doc(binding)
+            alldocs[key] = value
+        end
     end
-    return alldocs
+    alldocs
 end
 
 """
     findregions()
 
 Finds specific regions within a docstring and return them as a single string.
 """
-function findregions(docstring; regions=["formulation","description"], title="", fieldtitle=false, sep="\n\n", debugmode=false)
+function findregions(
+    docstring; regions=["formulation","description"], title="", fieldtitle=false, sep="\n\n", debugmode=false
+)
     md = ""
     if !isempty(title)
         md *= title * sep
@@ -396,7 +423,8 @@ function findregions(docstring; regions=["formulation","description"], title="",
         catch
             if debugmode
                 @warn "Cannot find #(end)region $region"
-                #the error could also be because there is no docstring for constraint but that is a very rare case as there is often at least a dynamic docstring
+                # the error could also be because there is no docstring for constraint but that is a very rare case
+                # as there is often at least a dynamic docstring
             end
         end
     end

docs/make.jl

@@ -1,32 +1,37 @@
 using Documenter
 using SpineOpt
 
+include("docs_utils.jl")
+
 # Automatically write the `Concept Reference` files using the `spineopt_template.json` as a basis.
 # Actual descriptions are fetched separately from `src/concept_reference/concepts/`
 path = @__DIR__
 default_translation = Dict(
-    #["tool_features"] => "Tool Features",
+    # ["tool_features"] => "Tool Features",
     ["relationship_classes"] => "Relationship Classes",
     ["parameter_value_lists"] => "Parameter Value Lists",
-    #["features"] => "Features",
-    #["tools"] => "Tools",
+    # ["features"] => "Features",
+    # ["tools"] => "Tools",
     ["object_parameters", "relationship_parameters"] => "Parameters",
     ["object_classes"] => "Object Classes",
 )
-concept_dictionary = SpineOpt.add_cross_references!(
-    SpineOpt.initialize_concept_dictionary(SpineOpt.template(); translation=default_translation),
+concept_dictionary = add_cross_references!(
+    initialize_concept_dictionary(SpineOpt.template(); translation=default_translation),
 )
-SpineOpt.write_concept_reference_files(concept_dictionary, path)
+write_concept_reference_files(concept_dictionary, path)
 
-# Automatically write the 'constraints_automatically_generated_file' file using the 'constraints' file and content from docstrings
+# Automatically write the 'constraints_automatically_generated_file' file using the 'constraints' file
+# and content from docstrings
 mathpath = joinpath(path, "src", "mathematical_formulation")
-alldocs = SpineOpt.alldocstrings(SpineOpt)
+alldocs = alldocstrings(SpineOpt)
 instructionlist = readlines(joinpath(mathpath, "constraints.md"))
-markdownstring = SpineOpt.docs_from_instructionlist(alldocs, instructionlist)
+markdownstring = docs_from_instructionlist(alldocs, instructionlist)
 open(joinpath(mathpath, "constraints_automatically_generated_file.md"), "w") do file
     write(file, markdownstring)
 end
 
+write_documentation_sets_variables(mathpath)
+
 # Generate the documentation pages
 # Replace the Any[...] with just Any[] if you want to collect content automatically via `expand_empty_chapters!`
 pages = [
@@ -77,7 +82,7 @@ pages = [
     "Implementation details" => [],
     "Library" => "library.md",
 ]
-SpineOpt.populate_empty_chapters!(pages, joinpath(path, "src"))
+populate_empty_chapters!(pages, joinpath(path, "src"))
 
 # Create and deploy the documentation
 makedocs(