Merge branch 'main' into models_documentation

powsybl · Jul 1, 2024 · e83f775 · e83f775
2 parents 52843cf + bcce6b1
commit e83f775
Show file tree

Hide file tree

Showing 47 changed files with 1,082 additions and 97 deletions.
diff --git a/.gitignore b/.gitignore
@@ -26,3 +26,6 @@ org.sonarlint.eclipse.core.prefs
 
 # Log files
 powsybl.log
+
+# Generated readthedocs pages
+build-docs/
diff --git a/README.md b/README.md
@@ -172,3 +172,57 @@ For the above example, the corresponding parameter file could be:
 
 
 Other examples can be found in the [resources](https://github.com/powsybl/powsybl-dynawo/tree/main/dynawaltz-dsl/src/test/resources) of this project.
+
+
+## Contribute to documentation
+
+The documentation sources for PowSybl Dynawo features are in the `docs` folder.
+
+Please keep them up to date with your developments.  
+They are published on https://powsybl.readthedocs.io and pull requests are built and previewed automatically via github CI.
+
+### Preview results
+When modifying the website content, you can easily preview the result by building the docs locally.
+To do so, run the following commands:
+~~~bash
+pip install -r docs/requirements.txt
+sphinx-build -a docs ./build-docs
+~~~
+Then open `build-docs/index.html` in your browser.
+
+### Cross-documentation links
+If you want to add links to another documentation, add the corresponding repository to the `conf.py` file.
+In order to automatically get the version specified in the `pom.xml`, please use the same naming as the version: if you define the
+Groovy version with `<groovy.version>`, then use `groovy` as key. The specified URL should start with `https://` and end with `latest/` (the final `/` is mandatory).
+For example, to add a link to the documentation of Sphinx, you need to add the following lines:
+~~~python
+# This parameter might already be present, just add the new value
+intersphinx_mapping = {
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+~~~
+
+Then in your documentation file, you can add links to Sphinx documentation. If you want to link to a whole page,
+use one of the following example:
+~~~Markdown
+- {doc}`sphinx:usage/extensions/intersphinx`
+- {doc}`Intersphinx <sphinx:usage/extensions/intersphinx>`
+- [Intersphinx](inv:sphinx:std:doc#usage/extensions/intersphinx).
+~~~
+
+If you want to link a specific part of a page, use one of those examples:
+~~~Markdown
+- [Intersphinx roles](inv:#ref-role).
+- [Intersphinx roles](inv:sphinx#ref-role).
+- [Intersphinx roles](inv:sphinx:std:label:#ref-role).
+- [Intersphinx roles](inv:sphinx:*:*:#ref-role).
+~~~
+*Note 1: for the last examples to work, there need to be a corresponding reference in the external documentation.
+For those examples, `(ref-role)=` has been added right before the corresponding title
+in the [Cross-referencing syntax page](inv:sphinx:std:doc#usage/referencing). Another way to make it work is to use the `autosectionlabel` module in Sphinx to
+automatically generate anchors for each title.*
+
+*Note 2: if the build fails, try with the `-E` option to clear the cache:*
+~~~bash
+sphinx-build -a -E docs ./build-docs
+~~~
diff --git a/commons/src/test/java/com/powsybl/dynawo/commons/AbstractDynawoCommonsTest.java b/commons/src/test/java/com/powsybl/dynawo/commons/AbstractDynawoCommonsTest.java
@@ -17,7 +17,7 @@
 import java.nio.file.Path;
 import java.util.Objects;
 
-import static com.powsybl.commons.test.ComparisonUtils.compareXml;
+import static com.powsybl.commons.test.ComparisonUtils.assertXmlEquals;
 
 /**
  * @author Florian Dupuy {@literal <florian.dupuy at rte-france.com>}
@@ -26,11 +26,11 @@ abstract class AbstractDynawoCommonsTest extends AbstractSerDeTest {
 
     protected void compare(String expectedIidmResource, Network actual) throws IOException {
         InputStream expected = Objects.requireNonNull(getClass().getResourceAsStream(expectedIidmResource));
-        compareXml(expected, getInputStream(actual, tmpDir.resolve("actual.xiidm")));
+        assertXmlEquals(expected, getInputStream(actual, tmpDir.resolve("actual.xiidm")));
     }
 
     protected void compare(Network expected, Network actual) throws IOException {
-        compareXml(getInputStream(expected, tmpDir.resolve("expected.xiidm")),
+        assertXmlEquals(getInputStream(expected, tmpDir.resolve("expected.xiidm")),
                 getInputStream(actual, tmpDir.resolve("actual.xiidm")));
     }
 

diff --git a/commons/src/test/resources/mergedLoadsMultiBusesVl.xiidm b/commons/src/test/resources/mergedLoadsMultiBusesVl.xiidm
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="multiBusesVl" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" id="multiBusesVl" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="substation">
         <iidm:voltageLevel id="vl1" nominalV="250.0" topologyKind="NODE_BREAKER">
             <iidm:nodeBreakerTopology>

diff --git a/commons/src/test/resources/mergedLoadsPnQn.xiidm b/commons/src/test/resources/mergedLoadsPnQn.xiidm
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="substation">
         <iidm:voltageLevel id="vl1" nominalV="250.0" topologyKind="NODE_BREAKER">
             <iidm:nodeBreakerTopology>

diff --git a/commons/src/test/resources/mergedLoadsPnQp.xiidm b/commons/src/test/resources/mergedLoadsPnQp.xiidm
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="substation">
         <iidm:voltageLevel id="vl1" nominalV="250.0" topologyKind="NODE_BREAKER">
             <iidm:nodeBreakerTopology>

diff --git a/commons/src/test/resources/mergedLoadsPpQn.xiidm b/commons/src/test/resources/mergedLoadsPpQn.xiidm
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="substation">
         <iidm:voltageLevel id="vl1" nominalV="250.0" topologyKind="NODE_BREAKER">
             <iidm:nodeBreakerTopology>

diff --git a/commons/src/test/resources/mergedLoadsPpQp.xiidm b/commons/src/test/resources/mergedLoadsPpQp.xiidm
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="substation">
         <iidm:voltageLevel id="vl1" nominalV="250.0" topologyKind="NODE_BREAKER">
             <iidm:nodeBreakerTopology>

diff --git a/commons/src/test/resources/mergedThreeLoadsGroups.xiidm b/commons/src/test/resources/mergedThreeLoadsGroups.xiidm
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="substation">
         <iidm:voltageLevel id="vl1" nominalV="250.0" topologyKind="NODE_BREAKER">
             <iidm:nodeBreakerTopology>

diff --git a/commons/src/test/resources/nonMergeableLoads.xiidm b/commons/src/test/resources/nonMergeableLoads.xiidm
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
+<iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" id="multiLoads" caseDate="2023-02-17T05:41:11.194+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
     <iidm:substation id="substation">
         <iidm:voltageLevel id="vl1" nominalV="250.0" topologyKind="NODE_BREAKER">
             <iidm:nodeBreakerTopology>

diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+
+clean:
+	@echo "Removing $(SOURCEDIR)/reference/api"
+	@rm -rf "$(SOURCEDIR)/reference/api"
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico
diff --git a/docs/_static/logos/logo_lfe_powsybl.svg b/docs/_static/logos/logo_lfe_powsybl.svg
diff --git a/docs/_static/styles/styles.css b/docs/_static/styles/styles.css
@@ -0,0 +1,6 @@
+/* The following code ensures font is not too big (Furo theme can make font too big on large screens) */
+@media(min-width:97em) {
+    html {
+        font-size: 100%
+    }
+}
diff --git a/docs/_templates/page.html b/docs/_templates/page.html
@@ -0,0 +1,101 @@
+<!--
+  ~ Copyright (c) 2024, RTE (http://www.rte-france.com)
+  ~ This Source Code Form is subject to the terms of the Mozilla Public
+  ~ License, v. 2.0. If a copy of the MPL was not distributed with this
+  ~ file, You can obtain one at http://mozilla.org/MPL/2.0/.
+  ~ SPDX-License-Identifier: MPL-2.0
+  -->
+
+{% extends "furo/page.html" %}
+
+{% block footer %}
+<div class="related-pages">
+  {% if next -%}
+  <a class="next-page" href="{{ next.link }}">
+    <div class="page-info">
+      <div class="context">
+        <span>{{ _("Next") }}</span>
+      </div>
+      <div class="title">{{ next.title }}</div>
+    </div>
+    <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+  </a>
+  {%- endif %}
+  {% if prev -%}
+  <a class="prev-page" href="{{ prev.link }}">
+    <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+    <div class="page-info">
+      <div class="context">
+        <span>{{ _("Previous") }}</span>
+      </div>
+      {% if prev.link == pathto(master_doc) %}
+      <div class="title">{{ _("Home") }}</div>
+      {% else %}
+      <div class="title">{{ prev.title }}</div>
+      {% endif %}
+    </div>
+  </a>
+  {%- endif %}
+</div>
+<div class="bottom-of-page">
+  <div class="left-details">
+    {%- if show_copyright %}
+    <div class="copyright">
+      {%- if hasdoc('copyright_year') %}
+      {% trans path=pathto('copyright_year'), copyright_year=copyright_year|e -%}
+      <p class="text-justify">
+        <a href="{{ path }}">Copyright</a> &#169; {{ copyright_year }}Authors of <a href="{{ github_repository }}">PowSyBl documentation</a>.
+        Unless otherwise indicated, content is licensed under <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">CC-BY-4.0</a>.
+      </p>
+      <p class="text-justify">
+        The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The
+        Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage">Trademark
+        Usage</a> page. Linux is a registered trademark of Linus Torvalds.
+      </p>
+      {%- endtrans %}
+      {%- else %}
+      {% trans copyright=copyright|e -%}
+      <p class="text-justify">
+        Copyright &#169; {{ copyright_year }} Authors of <a href="{{ github_repository }}">PowSyBl documentation</a>.
+        Unless otherwise indicated, content is licensed under <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">CC-BY-4.0</a>.
+      </p>
+      <p class="text-justify">
+        The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The
+        Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage">Trademark
+        Usage</a> page. Linux is a registered trademark of Linus Torvalds.
+      </p>
+      {%- endtrans %}
+      {%- endif %}
+    </div>
+    {%- endif %}
+    {% trans %}Made with {% endtrans -%}
+    {%- if show_sphinx -%}
+    {% trans %}<a href="https://www.sphinx-doc.org/">Sphinx</a> and {% endtrans -%}
+    <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
+    {% endif -%}
+    {% trans %}
+    <a href="https://github.com/pradyunsg/furo">Furo</a>
+    {% endtrans %}
+    {%- if last_updated -%}
+    <div class="last-updated">
+      {% trans last_updated=last_updated|e -%}
+      Last updated on {{ last_updated }}
+      {%- endtrans -%}
+    </div>
+    {%- endif %}
+  </div>
+  <div class="right-details">
+    {% if theme_footer_icons or READTHEDOCS -%}
+    <div class="icons">
+      {% if theme_footer_icons -%}
+      {% for icon_dict in theme_footer_icons -%}
+      <a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
+        {{- icon_dict.html -}}
+      </a>
+      {% endfor %}
+      {%- endif %}
+    </div>
+    {%- endif %}
+  </div>
+</div>
+{% endblock footer %}