Add readthedocs (#356)

* Add readthedocs 'docs' folder
* Reorder documents
* Add build-docs to gitignore
* Update documentation
* Review fix
* Add templates and config files, copied from powsybl-core
* Add contribute to documentation section in root README.md
* Add missing requirement
* Fix conf.py
* Add/fix links to powsybl-core APIs

Signed-off-by: lisrte <[email protected]>
Co-authored-by: Florian Dupuy <[email protected]>

.gitignore

@@ -26,3 +26,6 @@ org.sonarlint.eclipse.core.prefs
 
 # Log files
 powsybl.log
+
+# Generated readthedocs pages
+build-docs/

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
+~~~

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

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)

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%
+    }
+}

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 %}

docs/_templates/sidebar/brand.html

@@ -0,0 +1,25 @@
+{#-
+Overrides furo's brand.html to customize links:
+- The logo links to a custom page (set sidebar_logo_href option in html_context)
+- The title links to the subproject's main page
+-#}
+<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{% if sidebar_logo_href %} {{ sidebar_logo_href }} {% else %} {{ pathto(master_doc) }} {% endif %}">
+    {% block brand_content %}
+    {%- if logo_url %}
+    <div class="sidebar-logo-container">
+        <img class="sidebar-logo" src="{{ logo_url }}" alt="Logo"/>
+    </div>
+    {%- endif %}
+    {%- if theme_light_logo and theme_dark_logo %}
+    <div class="sidebar-logo-container">
+        <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" alt="Light Logo"/>
+        <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" alt="Dark Logo"/>
+    </div>
+    {%- endif %}
+    {% endblock brand_content %}
+</a>
+{% if not theme_sidebar_hide_name %}
+<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
+    <span class="sidebar-brand-text">{{ docstitle if docstitle else project }}</span>
+</a>
+{%- endif %}