RoseauTechnologies · benoit9126 · Sep 3, 2024 · Jul 9, 2024 · Sep 3, 2024 · Sep 3, 2024
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/Changelog.md b/doc/Changelog.md
@@ -19,6 +19,7 @@ og:description: See what's new in the latest release of Roseau Load Flow !
 
 ## Unreleased
 
+- {gh-pr}`237` Improvements of the Sphinx configuration.
 - {gh-pr}`262` Raise a proper error when a transformer is defined with null impedance.
 - {gh-pr}`259` The cache of the license object was not reset after the activation of a new license key.
 - {gh-pr}`258` {gh-pr}`261` {gh-pr}`263` Add basic plotting functionality in the new `roseau.load_flow.plotting`
@@ -201,7 +202,7 @@ Starting with version 0.7.0, Roseau Load Flow is no longer supplied as a SaaS. T
 a standalone Python library.
 ```
 
-- The documentation is moved from GitHub Pages to <https://www.roseau-load-flow.roseautechnologies.com/>.
+- The documentation is moved from GitHub Pages to <https://roseau-load-flow.roseautechnologies.com/>.
 - Fix a bug in the engine: it was impossible to change the parameters of center-tapped and single phase transformers.
 - {gh-pr}`179` Fix a bug in the propagation of potentials when a center-tapped transformer is used without neutral at
   the primary side.

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
@@ -33,7 +33,6 @@
 extensions = [
     "myst_parser",
     "sphinx.ext.mathjax",
-    "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.extlinks",
@@ -72,14 +71,6 @@
 # As these files are not meant to be built, they are automatically excluded from source files.
 html_extra_path = ["robots.txt", ".htaccess"]
 
-# -- 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 HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -129,12 +120,23 @@
 .. 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"]
 autoapi_options = ["members", "show-inheritance", "show-module-summary", "imported-members"]
 autoapi_python_class_content = "both"  # without this, the __init__ docstring is not shown
 autoapi_python_use_implicit_namespaces = True
+suppress_warnings = ["autoapi.python_import_resolution"]  # For the import of roseau.load_flow_engine.cy_engine
 
 # -- Options for intersphinx -------------------------------------------------
 intersphinx_mapping = {
@@ -147,6 +149,9 @@
     "typing_extensions": ("https://typing-extensions.readthedocs.io/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "networkx": ("https://networkx.org/documentation/stable/", None),
+    "pyproj": ("https://pyproj4.github.io/pyproj/stable/", None),
+    "certifi": ("https://certifiio.readthedocs.io/en/latest/", None),
+    "platformdirs": ("https://platformdirs.readthedocs.io/en/latest/", None),
 }
 
 # -- Options for sphinx_copybutton -------------------------------------------

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