diff --git a/docs/_static/styles/styles.css b/docs/_static/styles/styles.css new file mode 100644 index 000000000..f3340e112 --- /dev/null +++ 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% + } +} \ No newline at end of file diff --git a/docs/_templates/page.html b/docs/_templates/page.html new file mode 100644 index 000000000..4652e049e --- /dev/null +++ b/docs/_templates/page.html @@ -0,0 +1,101 @@ + + +{% extends "furo/page.html" %} + +{% block footer %} +
+ {% if next -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
+
+ + + {%- endif %} + {% if prev -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(master_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %} +
+ + {%- endif %} +
+
+
+ {%- if show_copyright %} +
+ {%- if hasdoc('copyright_year') %} + {% trans path=pathto('copyright_year'), copyright_year=copyright_year|e -%} +

+ Copyright © {{ copyright_year }}Authors of PowSyBl documentation. + Unless otherwise indicated, content is licensed under CC-BY-4.0. +

+

+ The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The + Linux Foundation, please see our Trademark + Usage page. Linux is a registered trademark of Linus Torvalds. +

+ {%- endtrans %} + {%- else %} + {% trans copyright=copyright|e -%} +

+ Copyright © {{ copyright_year }} Authors of PowSyBl documentation. + Unless otherwise indicated, content is licensed under CC-BY-4.0. +

+

+ The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The + Linux Foundation, please see our Trademark + Usage page. Linux is a registered trademark of Linus Torvalds. +

+ {%- endtrans %} + {%- endif %} +
+ {%- endif %} + {% trans %}Made with {% endtrans -%} + {%- if show_sphinx -%} + {% trans %}Sphinx and {% endtrans -%} + @pradyunsg's + {% endif -%} + {% trans %} + Furo + {% endtrans %} + {%- if last_updated -%} +
+ {% trans last_updated=last_updated|e -%} + Last updated on {{ last_updated }} + {%- endtrans -%} +
+ {%- endif %} +
+
+ {% if theme_footer_icons or READTHEDOCS -%} +
+ {% if theme_footer_icons -%} + {% for icon_dict in theme_footer_icons -%} + + {{- icon_dict.html -}} + + {% endfor %} + {%- endif %} +
+ {%- endif %} +
+
+{% endblock footer %} diff --git a/docs/_templates/sidebar/brand.html b/docs/_templates/sidebar/brand.html new file mode 100644 index 000000000..8aef92a7b --- /dev/null +++ b/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 +-#} + +{% if not theme_sidebar_hide_name %} + +{%- endif %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index db9bf0227..c2f2a358d 100644 --- a/docs/conf.py +++ b/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 ----------------------------------------------------- +# Only those 4 parameters have to be modified for each specific repository project = 'powsybl dynawo' -copyright = '2024, RTE (http://www.rte-france.com)' +module_name = "powsybl-dynawo" +github_repository = "https://github.com/powsybl/powsybl-dynawo/" + +# 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}\' + module_name + r'\<\/artifactId\>', line) + if m: + next_line_contains_version = True + else: + m = re.match(r'^ {4}\(.*)\<\/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,6 +61,7 @@ # 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', @@ -38,7 +69,9 @@ '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 = 'powsybl-dynawo' -html_short_title = 'powsybl-dynawo' +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-dynawo/", + "source_repository": github_repository, "source_branch": "main", "source_directory": "docs/", } @@ -91,9 +128,40 @@ # Links to external documentations : python 3 and pandas intersphinx_mapping = { - "powsyblcore": ("https://powsybl-core.readthedocs.io/en/latest/", None), } intersphinx_disabled_reftypes = ["*"] # Generate one file per method -autosummary_generate = True \ No newline at end of file +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 "" in line: + break + return intersphinx_mapping + +intersphinx_mapping = replace_versions(intersphinx_mapping, file_with_version) \ No newline at end of file