Update some directives

RoseauTechnologies · Sep 3, 2024 · 48366a4 · 48366a4
1 parent 9bd8ba6
commit 48366a4
Show file tree

Hide file tree

Showing 18 changed files with 597 additions and 541 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -15,7 +15,7 @@ repos:
     hooks:
       - id: poetry-check
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.1
+    rev: v0.6.3
     hooks:
       - id: ruff
         types_or: [python, pyi, jupyter]
@@ -29,13 +29,13 @@ repos:
         files: ^doc/.*\.md$
         args: [-l 90]
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.3.2
+    rev: v3.3.3
     hooks:
       - id: prettier
         args: ["--print-width", "120"]
         require_serial: true
   - repo: https://github.com/cmhughes/latexindent.pl
-    rev: V3.24.2
+    rev: V3.24.4
     hooks:
       - id: latexindent
         args: [-l, -m, -s, -wd]
diff --git a/doc/advanced/index.md b/doc/advanced/index.md
@@ -1,10 +1,9 @@
 This section explains some advanced concepts in _Roseau_Load_Flow_:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Advanced
----
+:maxdepth: 2
+:caption: Advanced
+
 Solvers
 Floating_Neutral
 Potential_Reference

diff --git a/doc/conf.py b/doc/conf.py
@@ -120,6 +120,16 @@
 .. role:: roseau-tertiary
 """
 
+
+# -- Options for autodoc ----------------------------------------------------
+autodoc_default_options = {"ignore-module-all": False}
+autodoc_member_order = "bysource"
+autodoc_typehints = "signature"
+autodoc_inherit_docstrings = True
+autoclass_content = "both"  # show both class and __init__ docstrings
+autodoc_mock_imports = ["roseau.load_flow_engine"]  # Ignore missing dependencies when building the documentation
+
+
 # -- Options for AutoAPI -------------------------------------------------
 autoapi_dirs = ["../roseau"]
 autoapi_ignore = ["**/tests/**", "**/conftest.py", "__about__.py"]

diff --git a/doc/index.md b/doc/index.md
@@ -36,10 +36,9 @@ More details are given in the [Catalogues page](catalogues-networks).
 and newer and can be installed with:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Installation and License
----
+:maxdepth: 2
+:caption: Installation and License
+
 Installation
 ```
 
@@ -48,9 +47,8 @@ Installation
 Read more about the license of this project:
 
 ```{toctree}
----
-maxdepth: 2
----
+:maxdepth: 2
+
 License
 ```
 
@@ -59,10 +57,9 @@ License
 The following tutorials are available to help you get started:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Usage
----
+:maxdepth: 2
+:caption: Usage
+
 usage/index
 ```
 
@@ -72,10 +69,9 @@ A description of the electrical models used for each component, an example usage
 to the API of the classes are available here:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Models
----
+:maxdepth: 2
+:caption: Models
+
 models/index
 ```
 
@@ -84,20 +80,18 @@ models/index
 Advanced concepts, edge cases and more are explained in this section:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Advanced
----
+:maxdepth: 2
+:caption: Advanced
+
 advanced/index
 ```
 
 ## Changelog
 
 ```{toctree}
----
-maxdepth: 2
-caption: More
----
+:maxdepth: 2
+:caption: More
+
 Changelog
 ```
 
@@ -107,8 +101,7 @@ If you want the full documentation of all the classes and functions, you can ref
 references:
 
 ```{toctree}
----
-maxdepth: 2
----
+:maxdepth: 2
+
 autoapi/roseau/load_flow/index
 ```
diff --git a/doc/models/Bus.md b/doc/models/Bus.md
@@ -107,7 +107,7 @@ en.res_lines[["current1"]].transform([np.abs, ft.partial(np.angle, deg=True)])
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.Bus
+.. autoapiclass:: roseau.load_flow.models.Bus
    :members:
    :show-inheritance:
    :no-index:

diff --git a/doc/models/Ground.md b/doc/models/Ground.md
@@ -152,7 +152,7 @@ en.res_buses_voltages.transform([np.abs, ft.partial(np.angle, deg=True)])
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.Ground
+.. autoapiclass:: roseau.load_flow.models.Ground
    :members:
    :show-inheritance:
    :no-index:

diff --git a/doc/models/Line/index.md b/doc/models/Line/index.md
@@ -183,10 +183,9 @@ The following line models are available in _Roseau Load Flow_. Please also have
 define the parameters of lines.
 
 ```{toctree}
----
-maxdepth: 2
-caption: Lines
----
+:maxdepth: 2
+:caption: Lines
+
 Parameters
 ShuntLine
 SimplifiedLine
@@ -195,11 +194,11 @@ SimplifiedLine
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.LineParameters
+.. autoapiclass:: roseau.load_flow.models.LineParameters
    :members:
    :show-inheritance:
    :no-index:
-.. autoclass:: roseau.load_flow.models.Line
+.. autoapiclass:: roseau.load_flow.models.Line
    :members:
    :show-inheritance:
    :no-index:

diff --git a/doc/models/Load/FlexibleLoad/index.md b/doc/models/Load/FlexibleLoad/index.md
@@ -59,10 +59,9 @@ The expression $\underline{S}(U)$ depends on four parameters:
 All these elements are detailed in the following sections:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Flexible loads
----
+:maxdepth: 2
+:caption: Flexible loads
+
 Control
 Projection
 FlexibleParameter
@@ -72,15 +71,15 @@ FeasibleDomain
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.Control
+.. autoapiclass:: roseau.load_flow.models.Control
    :members:
    :show-inheritance:
    :no-index:
-.. autoclass:: roseau.load_flow.models.Projection
+.. autoapiclass:: roseau.load_flow.models.Projection
    :members:
    :show-inheritance:
    :no-index:
-.. autoclass:: roseau.load_flow.models.FlexibleParameter
+.. autoapiclass:: roseau.load_flow.models.FlexibleParameter
     :members:
     :show-inheritance:
     :no-index:

diff --git a/doc/models/Load/index.md b/doc/models/Load/index.md
@@ -85,10 +85,9 @@ considers the voltage dependency of loads. ZIP stands for the three load types:
 The following load models are available in _Roseau Load Flow_:
 
 ```{toctree}
----
-maxdepth: 3
-caption: Loads
----
+:maxdepth: 3
+:caption: Loads
+
 ImpedanceLoad
 CurrentLoad
 PowerLoad
@@ -98,19 +97,19 @@ FlexibleLoad/index
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.AbstractLoad
+.. autoapiclass:: roseau.load_flow.models.AbstractLoad
    :members:
    :show-inheritance:
    :no-index:
-.. autoclass:: roseau.load_flow.models.ImpedanceLoad
+.. autoapiclass:: roseau.load_flow.models.ImpedanceLoad
    :members:
    :show-inheritance:
    :no-index:
-.. autoclass:: roseau.load_flow.models.CurrentLoad
+.. autoapiclass:: roseau.load_flow.models.CurrentLoad
     :members:
     :show-inheritance:
     :no-index:
-.. autoclass:: roseau.load_flow.models.PowerLoad
+.. autoapiclass:: roseau.load_flow.models.PowerLoad
     :members:
     :show-inheritance:
     :no-index:

diff --git a/doc/models/PotentialRef.md b/doc/models/PotentialRef.md
@@ -86,7 +86,7 @@ in the advanced section of the documentation.
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.PotentialRef
+.. autoapiclass:: roseau.load_flow.models.PotentialRef
    :members:
    :show-inheritance:
    :no-index:

diff --git a/doc/models/Switch.md b/doc/models/Switch.md
@@ -99,7 +99,7 @@ en.res_buses_voltages[["voltage"]].transform([np.abs, ft.partial(np.angle, deg=T
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.Switch
+.. autoapiclass:: roseau.load_flow.models.Switch
    :members:
    :show-inheritance:
    :no-index:

diff --git a/doc/models/Transformer/index.md b/doc/models/Transformer/index.md
@@ -188,10 +188,9 @@ A catalogue of transformer parameters is available. More details [here](catalogu
 The following transformer models are available in _Roseau Load Flow_:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Transformers
----
+:maxdepth: 2
+:caption: Transformers
+
 Single_Phase_Transformer
 Three_Phase_Transformer
 Center_Tapped_Transformer
@@ -200,11 +199,11 @@ Center_Tapped_Transformer
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.TransformerParameters
+.. autoapiclass:: roseau.load_flow.models.TransformerParameters
    :members:
    :show-inheritance:
    :no-index:
-.. autoclass:: roseau.load_flow.models.Transformer
+.. autoapiclass:: roseau.load_flow.models.Transformer
    :members:
    :show-inheritance:
    :no-index:

diff --git a/doc/models/VoltageSource.md b/doc/models/VoltageSource.md
@@ -202,7 +202,7 @@ rlf.VoltageSource(
 ## API Reference
 
 ```{eval-rst}
-.. autoclass:: roseau.load_flow.models.VoltageSource
+.. autoapiclass:: roseau.load_flow.models.VoltageSource
    :members:
    :show-inheritance:
    :no-index:

diff --git a/doc/models/index.md b/doc/models/index.md
@@ -1,10 +1,9 @@
 A description of the electrical models used for each component is available:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Models
----
+:maxdepth: 2
+:caption: Models
+
 PotentialRef
 Ground
 Bus

diff --git a/doc/usage/index.md b/doc/usage/index.md
@@ -1,10 +1,9 @@
 This section provides some tutorials to start using _Roseau_Load_Flow_:
 
 ```{toctree}
----
-maxdepth: 2
-caption: Usage
----
+:maxdepth: 2
+:caption: Usage
+
 Getting_Started
 Connecting_Elements
 Flexible_Loads