diff --git a/.gitignore b/.gitignore index e2aec9ab..a8d65505 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,6 @@ cmake-build*/ .cproject .project .settings/ + +# Generated readthedocs pages +build-docs/ diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 00000000..934aaace --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..4d15385e --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..d62c8f5a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,63 @@ +These are the documentation sources for PowSyBl iidm4cpp. + +Please keep them up to date with your developments. +They are published on powsybl.readthedocs.io/ and pull requests are built and previewed automatically. + +When modifying the website content, you can easily preview the result on your PC. + +**First option - in a terminal, navigate to the root of the project and run the following commands:** + +~~~ +pip install -r docs/requirements.txt +sphinx-build -a docs ./build-docs +~~~ + +**Second option - run the following commands directly from your IDE GUI** + +~~~bash +pip install -r requirements.txt +~~~ + +~~~bash +sphinx-build -a . ../build-docs +~~~ + +**Preview the result** + +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. +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 ``, then use `groovy` as a 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 examples: +~~~Markdown +- {doc}`sphinx:usage/extensions/intersphinx` +- {doc}`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 +~~~ diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 00000000..2ea6b5c3 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/logos/logo_lfe_powsybl.svg b/docs/_static/logos/logo_lfe_powsybl.svg new file mode 100644 index 00000000..37450078 --- /dev/null +++ b/docs/_static/logos/logo_lfe_powsybl.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/styles/styles.css b/docs/_static/styles/styles.css new file mode 100644 index 00000000..f3340e11 --- /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 00000000..4652e049 --- /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 00000000..8aef92a7 --- /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 new file mode 100644 index 00000000..4f874a39 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,113 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# 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 +source_path = os.path.abspath('..') +sys.path.insert(0, source_path) +print(f'appended {source_path}') + + +# -- Project information ----------------------------------------------------- + +# Only those 4 parameters have to be modified for each specific repository +project = 'powsybl-iidm4cpp' +module_name = "powsybl-iidm4cpp" +github_repository = "https://github.com/powsybl/powsybl-iidm4cpp/" + +# Build year for the copyright +copyright_year = f'2018-{ datetime.datetime.now().year }' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# 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', + # Extension used to add a "copy" button on code blocks + 'sphinx_copybutton'] +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "dollarmath", + "attrs_inline" +] +myst_heading_anchors = 6 + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# 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 ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "furo" + +html_title = f"{project}" + +html_logo = '_static/logos/logo_lfe_powsybl.svg' +html_favicon = "_static/favicon.ico" + +html_context = { + "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": github_repository, + "source_branch": "main", + "source_directory": "docs/", +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_css_files = ['styles/styles.css'] + +todo_include_todos = True + +# Links to external documentations +intersphinx_mapping = { + #"powsyblcore": ("https://powsybl.readthedocs.io/projects/powsybl-core/en/latest/", None), +} +intersphinx_disabled_reftypes = ["*"] + +# Generate one file per method +autosummary_generate = True + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..8b9e18af --- /dev/null +++ b/docs/index.md @@ -0,0 +1,22 @@ +![PowSyBl Logo](_static/logos/logo_lfe_powsybl.svg) +# PowSyBl iidm4cpp + +PowSyBl (Power System Blocks) is an open source library written in Java, +dedicated to electrical grid modeling, simulation and visualisation, licensed under the [Mozilla Public License version 2.0](https://www.mozilla.org/en-US/MPL/2.0/). +It is part of [LF Energy](https://www.lfenergy.org/), an open source foundation focused on the energy sector, hosted within The Linux Foundation. + +The powsybl-iidm4cpp repository is dedicated to a C++ implementation for IIDM. + +This readthedocs is dedicated to documenting the changes made to the repository in order to follow the evolution of IIDM. The changes are currently limited to what is necessary for the [dynawo project](https://github.com/dynawo). That means that IIDM features are not fully supported here. If you need some features to be added, please contact us via [Slack](https://powsybl.slack.com/archives/CGAAPNWTY). +In addition to those pages, please read the [README.md](https://github.com/powsybl/powsybl-iidm4cpp?tab=readme-ov-file#powsybl---iidm-for-c) to learn more about how to build the project. + +```{toctree} +--- +maxdepth: 2 +hidden: true +todo: + - fix links when pages are added +--- + +``` + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..96ed7097 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..c410d7c5 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx==7.1.2 +sphinx-tabs +furo==2024.1.29 +myst-parser +sphinx-copybutton \ No newline at end of file