uses the same docs' templates as those used in powsybl-core; extract …

…the current release from pyproject.toml

Signed-off-by: Christian Biasuzzi <[email protected]>

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,8 +10,10 @@
 # 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 sys
+import toml
 
 # Path to python sources, for doc generation on readthedocs
 source_path = os.path.abspath('..')
@@ -22,8 +24,37 @@
 # -- Project information -----------------------------------------------------
 
 project = 'pypowsybl-jupyter'
-copyright = '2024, RTE (http://www.rte-france.com)'
-
+github_repository = "https://github.com/powsybl/pypowsybl-jupyter/"
+copyright_year = f'{2024}' if datetime.datetime.now().year == 2024 else f'2024-{datetime.datetime.now().year}'
+
+# Find the release information.
+# We have a single source of truth for our version number: the project's pyproject.toml file.
+def extract_version_from_toml_file(file_path):
+    release = version = 'dev'
+    try:
+        # Load the pyproject.toml file
+        with open(file_path, 'r') as file:
+            pyproject_data = toml.load(file)
+
+        # Access the version attribute
+        read_version = pyproject_data.get('project', {}).get('version', None)
+
+        if read_version is not None:
+            release = read_version
+             # The short X.Y version.
+            version = ".".join(release.split(".")[:2])
+        else:
+            print(f"The 'version' attribute is not found in {file_path}.")
+
+    except FileNotFoundError:
+        print(f"The file {file_path} does not exist.")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+    return (release, version)
+
+file_with_version = os.path.join(source_path, "pyproject.toml")
+(release, version) = extract_version_from_toml_file(file_with_version)
 
 # -- General configuration ---------------------------------------------------
 
@@ -38,7 +69,10 @@
               '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",
@@ -63,19 +97,22 @@
 #
 html_theme = "furo"
 
-html_title = 'pypowsybl-jupyter'
+html_title = f"{project} v{release}"
+
 html_short_title = 'pypowsybl-jupyter'
 
 html_logo = '_static/logos/logo_lfe_powsybl.svg'
 html_favicon = "_static/favicon.ico"
 
 html_context = {
-    "sidebar_logo_href": "https://powsybl.readthedocs.org"
+    "sidebar_logo_href": "https://powsybl.readthedocs.org",
+    "copyright_year": copyright_year,
+    "github_repository": github_repository
 }
 
 html_theme_options = {
     # the following 3 lines enable edit button
-    "source_repository": "https://github.com/powsybl/TODO-addrepositoryname/",
+    "source_repository": github_repository,
     "source_branch": "main",
     "source_directory": "docs/",
 }

docs/requirements.txt

@@ -1,4 +1,6 @@
 sphinx==7.1.2
 sphinx-tabs
 furo==2024.1.29
-myst-parser
+myst-parser
+sphinx-copybutton
+toml