Add readthedocs documentation (#10)

* Add docs folder
* adds a basic getting started section to the docs
* adds a doc page for each widget
* moves the Getting started content to a separate page
* uses the same docs' templates as those used in powsybl-core; extract the current release from pyproject.toml

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

.gitignore

@@ -14,3 +14,5 @@ pypowsybl_jupyter/nbextension
 .idea/
 *.iml
 
+# Generated readthedocs pages
+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/README.md

@@ -0,0 +1,13 @@
+# README
+
+These are the documentation sources for //TODOaddRepositoryName features.
+
+Please keep them up to date with your developments.  
+They are published on powsybl.readthedocs.io/ and pull requests are built and previewed automatically.
+
+To build the docs locally, 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.

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