Doc: Index + Timeseries

docs/README.md

@@ -24,4 +24,40 @@ sphinx-build -a . ../build-docs
 
 **Preview the result**
 
-Then open `../build-docs/index.html` in your browser.
+Then open `build-docs/index.html` in your browser.
+
+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 PowSyBl-Core 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: 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²: if the build fails, try with the `-E` option to clear the cache:*
+~~~bash
+sphinx-build -a -E docs ./build-docs
+~~~

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

docs/conf.py

@@ -10,7 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import datetime
 import os
+import re
 import sys
 
 # Path to python sources, for doc generation on readthedocs
@@ -21,8 +23,36 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'powsybl core'
-copyright = '2024, RTE (http://www.rte-france.com)'
+# Only those 4 parameters have to be modified for each specific repository
+project = 'powsybl-core'
+module_name = "powsybl-core"
+github_repository = "https://github.com/powsybl/powsybl-core/"
+
+# Build year for the copyright
+copyright_year = f'2018-{ datetime.datetime.now().year }'
+
+# Find the version and release information.
+# We have a single source of truth for our version number: the project's pom.xml file.
+# This next bit of code reads from it.
+file_with_version = os.path.join(source_path, "pom.xml")
+with open(file_with_version) as f:
+    next_line_contains_version = False
+    for line in f:
+        if next_line_contains_version == False:
+            m = re.match(r'^ {4}\<artifactId\>' + module_name + r'\<\/artifactId\>', line)
+            if m:
+                next_line_contains_version = True
+        else:
+            m = re.match(r'^ {4}\<version\>(.*)\<\/version\>', line)
+            if m:
+                __version__ = m.group(1)
+                # The short X.Y version.
+                version = ".".join(__version__.split(".")[:2])
+                # The full version, including alpha/beta/rc tags.
+                release = __version__
+                break
+    else:  # AKA no-break
+        version = release = "dev"
 
 
 # -- General configuration ---------------------------------------------------
@@ -31,14 +61,17 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.autosectionlabel',
               'sphinx.ext.autosummary',
               'sphinx.ext.viewcode',
               'sphinx.ext.doctest',
               'sphinx.ext.napoleon',
               'sphinx.ext.todo',
               'sphinx.ext.intersphinx',
               'sphinx_tabs.tabs',
-              'myst_parser']
+              'myst_parser',
+              # Extension used to add a "copy" button on code blocks
+              'sphinx_copybutton']
 myst_enable_extensions = [
     "amsmath",
     "colon_fence",
@@ -55,6 +88,10 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# Reference sections generation
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -63,20 +100,20 @@
 #
 html_theme = "furo"
 
-html_title = 'core'
-html_short_title = 'core'
+html_title = f"{project} v{release}"
 
 html_logo = '_static/logos/logo_lfe_powsybl.svg'
 html_favicon = "_static/favicon.ico"
 
 html_context = {
-    # TODO : replace next option with "https://powsybl.readthedocs.org" when website is published
-    "sidebar_logo_href": "https://www.powsybl.org/"
+    "copyright_year": copyright_year,
+    "sidebar_logo_href": "https://powsybl.readthedocs.io/",
+    "github_repository": github_repository
 }
 
 html_theme_options = {
     # the following 3 lines enable edit button
-    "source_repository": "https://github.com/powsybl/powsybl-core/",
+    "source_repository": github_repository,
     "source_branch": "main",
     "source_directory": "docs/",
 }
@@ -95,4 +132,36 @@
 intersphinx_disabled_reftypes = ["*"]
 
 # Generate one file per method
-autosummary_generate = True
+autosummary_generate = True
+
+
+# -- Dependencies versions ---------------------------------------------------
+# This part will automatically look in the pom.xml to find versions corresponding to the dependencies whose
+# documentation is used in the present one, except if it's a SNAPSHOT version or if a specific version has been chosen
+# in intersphinx_mapping
+
+# Get the URL without the default version
+def extract_base_url(url):
+    default_version = "latest"
+
+    m = re.match(r'(^https\:\/\/.*)' + default_version + r'\/$', url)
+    if m:
+        return m.group(1)
+
+# Replace the default version in the URL with the version from the pom.xml
+def replace_versions(intersphinx_mapping, file):
+    with open(file) as f:
+        for line in f:
+            m = re.match(r'^ {8}\<(.*)\.version\>(.*)\<\/(.*)\.version\>', line)
+            if m and m.group(1) == m.group(3):
+                dependency = m.group(1)
+                version = m.group(2)
+                if "SNAPSHOT" not in version and dependency in intersphinx_mapping:
+                    url_start = extract_base_url(intersphinx_mapping[dependency][0])
+                    if url_start:
+                        intersphinx_mapping[dependency] = (url_start + version + "/", None)
+            if "</properties>" in line:
+                break
+    return intersphinx_mapping
+
+intersphinx_mapping = replace_versions(intersphinx_mapping, file_with_version)