Merge pull request #267 from JuliaReach/schillic/docs

Polish documentation
JuliaReach · Oct 16, 2023 · c994bdc · c994bdc
2 parents d4fec28 + 642a7c4
commit c994bdc
Show file tree

Hide file tree

Showing 5 changed files with 28 additions and 39 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -7,10 +7,10 @@ DocMeta.setdocmeta!(MathematicalSystems, :DocTestSetup,
 makedocs(; sitename="MathematicalSystems.jl",
          modules=[MathematicalSystems],
          format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true",
-                                assets=["assets/aligned.css"]),
+                                assets=["assets/aligned.css"], size_threshold_warn=150 * 2^10),
          pagesonly=true,
          pages=["Home" => "index.md",
-                "Manual" => Any["System types overview" => "man/systems.md"],
+                "Manual" => Any["Overview of System Types" => "man/systems.md"],
                 "Library" => Any["Types"     => "lib/types.md",
                                  "Methods"   => "lib/methods.md",
                                  "Internals" => "lib/internals.md"],

diff --git a/docs/src/lib/internals.md b/docs/src/lib/internals.md
@@ -14,7 +14,7 @@ DocTestSetup = quote
 end
 ```
 
-## Expression handling
+## Expression Handling
 
 ```@docs
 _corresponding_type
@@ -24,20 +24,20 @@ add_asterisk
 sort
 ```
 
-## Querying expressions
+## Querying Expressions
 
 ```@docs
 is_equation
 extract_sum
 ```
 
-## Evaluation of AbstractSystem at given state
+## Evaluation of AbstractSystem at Given State
 
 ```@docs
 _instantiate
 ```
 
-## Naming convention for systems' fields
+## Naming Convention for Systems' Fields
 
 Systems' fields should be accessed externally by their respective getter functions.
 Internally to the library, the following naming conventions are used.

diff --git a/docs/src/lib/types.md b/docs/src/lib/types.md
@@ -104,34 +104,22 @@ ExactDiscretization
 EulerDiscretization
 ```
 
-## System macro
-
-```@docs
-@system
-```
-
-## Initial-value problem macro
+## Initial Value Problems
 
 ```@docs
-@ivp
+InitialValueProblem
+IVP
+initial_state
+system
 ```
 
-## Identity operator
+## Identity Operator
 
 ```@docs
 IdentityMultiple
 Id
 ```
 
-## Initial Value Problems
-
-```@docs
-InitialValueProblem
-IVP
-initial_state
-system
-```
-
 ## Input Types
 
 ```@docs
@@ -162,22 +150,23 @@ BlackBoxControlMap
 ConstrainedBlackBoxControlMap
 ```
 
-### Macros
-
-```@docs
-@map
-```
-
-## Systems with output
+## Systems with Output
 
 ```@docs
 SystemWithOutput
 LinearTimeInvariantSystem
 LTISystem
 ```
 
-
-## Vector Field
+## Vector Fields
 ```@docs
 VectorField
 ```
+
+## Macros
+
+```@docs
+@system
+@ivp
+@map
+```
diff --git a/docs/src/man/systems.md b/docs/src/man/systems.md
@@ -1,6 +1,6 @@
-# System types overview
+# Overview of System Types
 
-## Using the macro
+## Using the `@system` Macro
 
 A convenient way to create a new system is with the `@system` macro. For example,
 the ODE $x'(t) = -2x(t)$ is simply `x' = -2x`, where $x'(t) := dx/dt$ is the derivative
@@ -56,7 +56,7 @@ for (controlled) inputs and noise respectively. Please note that some systems ar
 equivalent, for example `CLCCS` and `NCLCS` being $x' = Ax + Bu$ and $x' = Ax + Dw$ respectively;
 the difference lies in the resulting value of getter functions such as `inputset` and `noiseset`.
 
-## Summary tables
+## Summary Tables
 
 The following table summarizes the different system types in abbreviated form.
 The abbreviated names are included here only for reference and are not exported.

diff --git a/src/discretize.jl b/src/discretize.jl
@@ -45,7 +45,7 @@ The resulting discretization writes as
 
 The algorithm described above is a well known result from the literature [1].
 
-[1] https://en.wikipedia.org/wiki/Discretization#Discretization_of_linear_state_space_models
+[1] [Wikipedia](https://en.wikipedia.org/wiki/Discretization#Discretization_of_linear_state_space_models)
 """
 struct ExactDiscretization <: AbstractDiscretizationAlgorithm end
 
@@ -71,9 +71,9 @@ The resulting discretization writes as
 where  ``A^d = I + ΔT ~ A``, ``B^d = ΔT ~ B``,
 ``c^d = ΔT ~ c`` and ``D^d = ΔT ~ D``.
 
-The algorithm described above is a well known result from the literature [1].
+The algorithm described above is a well-known result from the literature [1].
 
-[1] https://en.wikipedia.org/wiki/Discretization#Approximations
+[1] [Wikipedia](https://en.wikipedia.org/wiki/Discretization#Approximations)
 """
 struct EulerDiscretization <: AbstractDiscretizationAlgorithm end