Merge pull request #487 from LCSB-BioCore/mk-reorg-docs

Reorganize the API docs to nice sections

docs/make.jl

@@ -51,6 +51,9 @@ cp(
     force = true,
 )
 
+find_mds(path) =
+    joinpath.(Ref(path), filter(x -> endswith(x, ".md"), readdir(joinpath("src", path))))
+
 # build the docs
 makedocs(
     modules = [COBREXA],
@@ -66,10 +69,21 @@ makedocs(
     linkcheck = !("skiplinks" in ARGS),
     pages = [
         "Home" => "index.md",
-        "Quickstart tutorials" => "tutorials.md",
-        "Advanced tutorials" => "advanced.md",
-        "Examples and notebooks" => "notebooks.md",
-        "Function reference" => "functions.md",
+        "User guide" => [
+            "Quickstart tutorials" => vcat(
+                "Detailed tutorial listing" => "tutorials.md",
+                find_mds("tutorials"),
+            ),
+            "Advanced tutorials" => vcat(
+                "Detailed tutorial listing" => "advanced.md",
+                find_mds("advanced"),
+            ),
+            "Examples and notebooks" => vcat(
+                "Detailed notebook listing" => "notebooks.md",
+                find_mds("notebooks"),
+            ),
+        ],
+        "API reference" => vcat("Contents" => "functions.md", find_mds("functions")),
         "How to contribute" => "howToContribute.md",
     ],
 )

docs/src/functions.md

-# Functions
+# Types and functions
 
-## Base Types
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("base", "types", "abstract", file), readdir("../src/base/types/abstract"))
-```
-
-## Model types and contents
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("base", "types", file), readdir("../src/base/types"))
-```
-
-## Base functions
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("base", file), readdir("../src/base"))
-```
-
-## File I/O and serialization
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("io", file), readdir("../src/io"))
-```
-
-### Pretty printing
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("io", "show", file), readdir("../src/io/show"))
-```
-
-## Model reconstruction
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("reconstruction", file), readdir("../src/reconstruction"))
-```
-
-### Model variant specifications
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("reconstruction", "modifications", file), readdir("../src/reconstruction/modifications"))
-```
-
-## Analysis functions
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("analysis", file), readdir("../src/analysis"))
-```
-
-### Analysis modifications
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("analysis", "modifications", file), readdir("../src/analysis/modifications"))
-```
-
-### Flux sampling
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("analysis", "sampling", file), readdir("../src/analysis/sampling"))
-```
-
-## Miscellaneous utilities
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("base", "utils", file), readdir("../src/base/utils"))
-```
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("base", "macros", file), readdir("../src/base/macros"))
-```
-
-### Logging and debugging helpers
-
-```@autodocs
-Modules = [COBREXA]
-Pages = map(file -> joinpath("base", "logging", file), readdir("../src/base/logging"))
+```@contents
+Pages = joinpath.("functions", filter(x -> endswith(x, ".md"), readdir("functions")))
+Depth = 2
 ```

docs/src/functions/analysis.md

+# Analysis functions
+
+## Common analysis functions
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("analysis", file), readdir("../src/analysis"))
+```
+
+## Sampling
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("analysis", "sampling", file), readdir("../src/analysis/sampling"))
+```
+
+## Analysis modifiers
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("analysis", "modifications", file), readdir("../src/analysis/modifications"))
+```

docs/src/functions/base.md

+# Base functions
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("base", file), readdir("../src/base"))
+```

docs/src/functions/io.md

+# Input and output
+
+## File I/O and serialization
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("io", file), readdir("../src/io"))
+```
+
+## Pretty printing
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("io", "show", file), readdir("../src/io/show"))
+```

docs/src/functions/reconstruction.md

+# Model construction functions
+
+## Functions for changing the models
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("reconstruction", file), readdir("../src/reconstruction"))
+```
+
+## Variant specifiers
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("reconstruction", "modifications", file), readdir("../src/reconstruction/modifications"))
+```

docs/src/functions/types.md

+# Types
+
+## Base types
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("base", "types", "abstract", file), readdir("../src/base/types/abstract"))
+```
+
+## Model types and contents
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("base", "types", file), readdir("../src/base/types"))
+```

docs/src/functions/utils.md

+# Utilities
+
+## Helper functions
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("base", "utils", file), readdir("../src/base/utils"))
+```
+
+## Macro-generated functions and internal helpers
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("base", "macros", file), readdir("../src/base/macros"))
+```
+
+## Logging and debugging helpers
+
+```@autodocs
+Modules = [COBREXA]
+Pages = map(file -> joinpath("base", "logging", file), readdir("../src/base/logging"))
+```

docs/src/tutorials/4_modifying.md

@@ -79,9 +79,11 @@ m.reactions["R_GLNS"].metabolites["M_co2_e"] = 1.0
 ```
 
 There are other functions that may be used to change the `StandardModel` in a
-more systematic way. See the documentation of [`add_reaction!`](@ref), [`add_metabolite!`](@ref),
-[`add_gene!`](@ref), [`remove_reaction!`](@ref), [`remove_metabolite!`](@ref),
-[ [`remove_gene!`](@ref), and the [Model reconstruction](@ref) reference for more examples.
+more systematic way. See the documentation of [`add_reaction!`](@ref),
+[`add_metabolite!`](@ref), [`add_gene!`](@ref), [`remove_reaction!`](@ref),
+[`remove_metabolite!`](@ref), [ [`remove_gene!`](@ref),
+and the [Model construction functions](@ref) reference section for more
+examples.
 
 ## Analysis modifiers
 

src/base/macros/serialized.jl

@@ -9,7 +9,7 @@ macro _serialized_change_unwrap(fn::Symbol)
     docstring = """
         $fn(model::Serialized, ...)
 
-    Calls [$fn](@ref) of the internal serialized model type.
+    Calls [`$fn`](@ref) of the internal serialized model type.
     Returns the modified un-serialized model.
     """
     :(@doc $docstring $fn(model::Serialized, args...; kwargs...) =

src/reconstruction/SerializedModel.jl

 
 # this just generates the necessary wrappers
 
+@_serialized_change_unwrap add_reactions
 @_serialized_change_unwrap change_bound
 @_serialized_change_unwrap change_bounds
-@_serialized_change_unwrap add_reaction
-@_serialized_change_unwrap remove_reaction
-@_serialized_change_unwrap remove_reactions
 @_serialized_change_unwrap remove_metabolite
 @_serialized_change_unwrap remove_metabolites
+@_serialized_change_unwrap remove_reaction
+@_serialized_change_unwrap remove_reactions
 
 """
     unwrap_serialized(model::Serialized)