Various doc and style improvements (SciML#150)

* format markdown

* strict links

* LanguageTool

.JuliaFormatter.toml

@@ -1 +1,2 @@
-style = "sciml"
+style = "sciml"
+format_markdown = true

README.md

@@ -6,7 +6,7 @@
 [![codecov](https://codecov.io/gh/SciML/ModelingToolkitStandardLibrary.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/SciML/ModelingToolkitStandardLibrary.jl)
 [![Build Status](https://github.com/SciML/ModelingToolkitStandardLibrary.jl/workflows/CI/badge.svg)](https://github.com/SciML/ModelingToolkitStandardLibrary.jl/actions?query=workflow%3ACI)
 
-[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
 The ModelingToolkit Standard Library is a standard library of components to model the world and beyond.
@@ -19,7 +19,8 @@ Assuming that you already have Julia correctly installed, it suffices to import
 ModelingToolkitStandardLibrary.jl in the standard way:
 
 ```julia
-import Pkg; Pkg.add("ModelingToolkitStandardLibrary")
+import Pkg;
+Pkg.add("ModelingToolkitStandardLibrary");
 ```
 
 ## Tutorials and Documentation
@@ -33,11 +34,11 @@ the documentation, which contains the unreleased features.
 
 The following are the constituant libraries of the ModelingToolkit Standard Library.
 
-- [Basic Blocks](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/blocks/)
-- [Mechanical Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/mechanical/)
-- [Electrical Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/electrical/)
-- [Magnetic Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/magnetic/)
-- [Thermal Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/thermal/)
+  - [Basic Blocks](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/blocks/)
+  - [Mechanical Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/mechanical/)
+  - [Electrical Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/electrical/)
+  - [Magnetic Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/magnetic/)
+  - [Thermal Components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/thermal/)
 
 ## Example
 
@@ -52,20 +53,19 @@ R = 1.0
 C = 1.0
 V = 1.0
 @variables t
-@named resistor = Resistor(R=R)
-@named capacitor = Capacitor(C=C)
+@named resistor = Resistor(R = R)
+@named capacitor = Capacitor(C = C)
 @named source = Voltage()
-@named constant = Constant(k=V)
+@named constant = Constant(k = V)
 @named ground = Ground()
 
-rc_eqs = [
-        connect(constant.output, source.V)
-        connect(source.p, resistor.p)
-        connect(resistor.n, capacitor.p)
-        connect(capacitor.n, source.n, ground.g)
-        ]
+rc_eqs = [connect(constant.output, source.V)
+          connect(source.p, resistor.p)
+          connect(resistor.n, capacitor.p)
+          connect(capacitor.n, source.n, ground.g)]
 
-@named rc_model = ODESystem(rc_eqs, t, systems=[resistor, capacitor, constant, source, ground])
+@named rc_model = ODESystem(rc_eqs, t,
+                            systems = [resistor, capacitor, constant, source, ground])
 sys = structural_simplify(rc_model)
 prob = ODEProblem(sys, Pair[], (0, 10.0))
 sol = solve(prob, Tsit5())

docs/make.jl

@@ -18,7 +18,9 @@ makedocs(sitename = "ModelingToolkitStandardLibrary.jl",
          authors = "Julia Computing",
          clean = true,
          doctest = false,
+         linkcheck = true,
          strict = [
+             :linkcheck,
              :doctest,
              :example_block,
          ],

docs/src/API/blocks.md

@@ -1,11 +1,15 @@
 # ModelingToolkitStandardLibrary: Blocks
+
 ```@meta
 CurrentModule = ModelingToolkitStandardLibrary.Blocks
 ```
+
 ```@contents
 Pages = ["blocks.md"]
 ```
+
 ## Index
+
 ```@index
 Pages = ["blocks.md"]
 ```
@@ -80,4 +84,4 @@ PI
 LimPI
 PID
 LimPID
-```
+```

docs/src/API/electrical.md

@@ -1,13 +1,15 @@
 # ModelingToolkitStandardLibrary: Electrical Components
+
 ```@meta
 CurrentModule = ModelingToolkitStandardLibrary.Electrical
 ```
 
-
 ```@contents
 Pages = ["electrical.md"]
 ```
+
 ## Index
+
 ```@index
 Pages = ["electrical.md"]
 ```
@@ -63,6 +65,7 @@ ExpSineCurrent
 ```
 
 ## Digital Gates
+
 ```@docs
 Not
 And
@@ -74,6 +77,7 @@ Xnor
 ```
 
 ## Digital Components
+
 ```@docs
 HalfAdder
 FullAdder
@@ -84,6 +88,7 @@ Decoder
 ```
 
 ## Digital Sources
+
 ```@docs
 PulseDiff
 Set

docs/src/API/linear_analysis.md

@@ -1,40 +1,48 @@
 # Linear Analysis
 
 !!! danger "Experimental"
-    The interface described here is currently experimental and at any time subject to breaking changes not respecting semantic versioning. 
+
+    The interface described here is currently experimental and at any time subject to breaking changes not respecting semantic versioning.
 
 Linear analysis refers to the process of linearizing a nonlinear model and analysing the resulting linear dynamical system. To facilitate linear analysis, ModelingToolkitStandardLibrary provides the concept of an [`AnalysisPoint`](@ref), which can be inserted in-between two causal blocks (such as those from the `Blocks` sub module). Once a model containing analysis points is built, several operations are available:
 
-- [`get_sensitivity`](@ref) get the [sensitivity function (wiki)](https://en.wikipedia.org/wiki/Sensitivity_(control_systems)), $S(s)$, as defined in the field of control theory.
-- [`get_comp_sensitivity`](@ref) get the complementary sensitivity function $T(s) : S(s)+T(s)=1$.
-- [`get_looptransfer`](@ref) get the (open) loop-transfer function where the loop starts and ends in the analysis point. For a typical simple feedback connection with a plant $P(s)$ and a controller $C(s)$, the loop-transfer function at the plant output is $P(s)C(s)$.
-- [`linearize`](@ref) can be called with two analysis points denoting the input and output of the linearized system.
-- [`open_loop`](@ref) return a new (nonlinear) system where the loop has been broken in the analysis point, i.e., the connection the analysis point usually implies has been removed.
+  - [`get_sensitivity`](@ref) get the [sensitivity function (wiki)](https://en.wikipedia.org/wiki/Sensitivity_(control_systems)), $S(s)$, as defined in the field of control theory.
+  - [`get_comp_sensitivity`](@ref) get the complementary sensitivity function $T(s) : S(s)+T(s)=1$.
+  - [`get_looptransfer`](@ref) get the (open) loop-transfer function where the loop starts and ends in the analysis point. For a typical simple feedback connection with a plant $P(s)$ and a controller $C(s)$, the loop-transfer function at the plant output is $P(s)C(s)$.
+  - [`linearize`](@ref) can be called with two analysis points denoting the input and output of the linearized system.
+  - [`open_loop`](@ref) return a new (nonlinear) system where the loop has been broken in the analysis point, i.e., the connection the analysis point usually implies has been removed.
 
 An analysis point can be created explicitly using the constructor [`AnalysisPoint`](@ref), or automatically when connecting two causal components using `connect`:
+
 ```julia
 connect(comp1.output, :analysis_point_name, comp2.input)
 ```
 
 !!! warning "Causality"
-    Analysis points are *causal*, i.e., they imply a directionality for the flow of information. The order of the connections in the connect statement is thus important, i.e., `connect(out, :name, in)` is different from `connect(in, :name, out)`.
 
+    Analysis points are *causal*, i.e., they imply a directionality for the flow of information. The order of the connections in the connect statement is thus important, i.e., `connect(out, :name, in)` is different from `connect(in, :name, out)`.
+
 The directionality of an analysis point can be thought of as an arrow in a block diagram, where the name of the analysis point applies to the arrow itself.
+
 ```
 ┌─────┐         ┌─────┐
 │     │  name   │     │
 │  out├────────►│in   │
 │     │         │     │
 └─────┘         └─────┘
 ```
+
 This is signified by the name being the middle argument to `connect`.
 
 Of the above mentioned functions, all except for [`open_loop`](@ref) return the output of [`ModelingToolkit.linearize`](@ref), which is
+
 ```julia
 matrices, simplified_sys = linearize(...)
 # matrices = (; A, B, C, D)
 ```
+
 i.e., `matrices` is a named tuple containing the matrices of a linear state-space system on the form
+
 ```math
 \begin{aligned}
 \dot x &= Ax + Bu\\
@@ -43,29 +51,31 @@ y &= Cx + Du
 ```
 
 ## Example
+
 The following example builds a simple closed-loop system with a plant $P$ and a controller $C$. Two analysis points are inserted, one before and one after $P$. We then derive a number of sensitivity functions and show the corresponding code using the package ControlSystemBase.jl
 
 ```@example LINEAR_ANALYSIS
 using ModelingToolkitStandardLibrary.Blocks, ModelingToolkit
-@named P = FirstOrder(k=1, T=1) # A first-order system with pole in -1
+@named P = FirstOrder(k = 1, T = 1) # A first-order system with pole in -1
 @named C = Gain(-1)             # A P controller
 t = ModelingToolkit.get_iv(P)
-eqs = [
-    connect(P.output, :plant_output, C.input)  # Connect with an automatically created analysis point called :plant_output
-    connect(C.output, :plant_input, P.input)   # Connect with an automatically created analysis point called :plant_input
-]
-sys = ODESystem(eqs, t, systems=[P,C], name=:feedback_system)
+eqs = [connect(P.output, :plant_output, C.input)  # Connect with an automatically created analysis point called :plant_output
+       connect(C.output, :plant_input, P.input)]
+sys = ODESystem(eqs, t, systems = [P, C], name = :feedback_system)
 
 matrices_S = get_sensitivity(sys, :plant_input)[1] # Compute the matrices of a state-space representation of the (input)sensitivity function.
 matrices_T = get_comp_sensitivity(sys, :plant_input)[1]
 ```
+
 Continued linear analysis and design can be performed using ControlSystemsBase.jl.
 We create `ControlSystemsBase.StateSpace` objects using
+
 ```@example LINEAR_ANALYSIS
 using ControlSystemsBase, Plots
 S = ss(matrices_S...)
 T = ss(matrices_T...)
-bodeplot([S, T], lab=["S" "" "T" ""], plot_title="Bode plot of sensitivity functions", margin=5Plots.mm)
+bodeplot([S, T], lab = ["S" "" "T" ""], plot_title = "Bode plot of sensitivity functions",
+         margin = 5Plots.mm)
 ```
 
 The sensitivity functions obtained this way should be equivalent to the ones obtained with the code below
@@ -84,38 +94,50 @@ We may also derive the loop-transfer function $L(s) = P(s)C(s)$ using
 matrices_L = get_looptransfer(sys, :plant_output)[1]
 L = ss(matrices_L...)
 ```
+
 which is equivalent to the following with ControlSystems
+
 ```@example LINEAR_ANALYSIS_CS
-L = P*(-C) # Add the minus sign to build the negative feedback into the controller
+L = P * (-C) # Add the minus sign to build the negative feedback into the controller
 ```
 
-
 To obtain the transfer function between two analysis points, we call `linearize`
+
 ```@example LINEAR_ANALYSIS
 using ModelingToolkit # hide
 matrices_PS = linearize(sys, :plant_input, :plant_output)[1]
 ```
+
 this particular transfer function should be equivalent to the linear system `P(s)S(s)`, i.e., equivalent to
+
 ```@example LINEAR_ANALYSIS_CS
 feedback(P, C)
 ```
 
 ### Obtaining transfer functions
+
 A statespace system from [ControlSystemsBase](https://juliacontrol.github.io/ControlSystems.jl/stable/man/creating_systems/) can be converted to a transfer function using the function `tf`:
+
 ```@example LINEAR_ANALYSIS_CS
 tf(S)
 ```
 
 ## Gain and phase margins
+
 Further linear analysis can be performed using the [analysis methods from ControlSystemsBase](https://juliacontrol.github.io/ControlSystems.jl/stable/lib/analysis/). For example, calculating the gain and phase margins of a system can be done using
+
 ```@example LINEAR_ANALYSIS_CS
 margin(P)
 ```
-(they are infinite for this system). A Nyquist plot can be produced using 
+
+(they are infinite for this system). A Nyquist plot can be produced using
+
 ```@example LINEAR_ANALYSIS_CS
 nyquistplot(P)
 ```
+
 ## Index
+
 ```@index
 Pages = ["linear_analysis.md"]
 ```

docs/src/API/magnetic.md

@@ -1,14 +1,17 @@
 # ModelingToolkitStandardLibrary: Magnetic Components
 
-
 ```@contents
 Pages = ["magnetic.md"]
 ```
+
 ## Index
+
 ```@index
 Pages = ["magnetic.md"]
 ```
+
 ## Flux Tubes
+
 ```@meta
 CurrentModule = ModelingToolkitStandardLibrary.Magnetic.FluxTubes
 ```
@@ -39,4 +42,4 @@ ElectroMagneticConverter
 ```@docs
 ConstantMagneticPotentialDifference
 ConstantMagneticFlux
-```
+```

docs/src/API/mechanical.md

@@ -1,16 +1,18 @@
 # ModelingToolkit Standard Library: Mechanical Components
 
-
 ```@contents
 Pages = ["mechanical.md"]
 Depth = 3
 ```
+
 ## Index
+
 ```@index
 Pages = ["mechanical.md"]
 ```
 
 ## Rotational Components
+
 ```@meta
 CurrentModule = ModelingToolkitStandardLibrary.Mechanical.Rotational
 ```

docs/src/API/thermal.md

@@ -1,13 +1,15 @@
 # ModelingToolkitStandardLibrary: Thermal Components
+
 ```@meta
 CurrentModule = ModelingToolkitStandardLibrary.Thermal
 ```
 
-
 ```@contents
 Pages = ["thermal.md"]
 ```
+
 ## Index
+
 ```@index
 Pages = ["thermal.md"]
 ```
@@ -46,4 +48,4 @@ FixedHeatFlow
 FixedTemperature
 PrescribedHeatFlow
 PrescribedTemperature  
-```
+```