Merge pull request #21 from alliander-opensource/feature/auto-api-doc

readthedocs documentation

.gitignore

@@ -25,3 +25,10 @@ data/
 # IDE
 .idea/
 .vscode/
+
+# docs
+docs/_build/
+docs/_static/
+docs/_templates/
+docs/make.bat
+docs/Makefile

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2022 Contributors to the Power Grid Model project <[email protected]>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+version: 2
+
+# Build from the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.9"
+  jobs:
+    post_install:
+      # Build package with doc requirements from pyproject.optional-dependencies
+      - pip install --verbose --editable .[doc]

docs/conf.py

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: 2022 Contributors to the Power Grid Model project <[email protected]>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "power-grid-model-io"
+copyright = "2022, alliander-opensource"
+author = "alliander-opensource"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "numpydoc",
+    "hoverxref.extension",
+    "myst_parser",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+# -- myst parser config ------------------------------------------------------
+# label references for depth of headers: label name in anchor slug structure
+myst_heading_anchors = 3
+
+# -- hoverxref config --------------------------------------------------------
+# hover tooltip on python classes
+hoverxref_domains = [
+    "py",
+]
+hoverxref_default_type = "tooltip"
+hoverxref_role_types = {
+    "hoverxref": "tooltip",
+    "ref": "modal",  # for hoverxref_auto_ref config
+    "confval": "tooltip",  # for custom object
+    "mod": "tooltip",  # for Python Sphinx Domain
+    "class": "tooltip",  # for Python Sphinx Domain
+}
+
+# -- sphinx.autodoc config ---------------------------------------------------
+autodoc_default_options = {
+    "members": None,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": False,
+    "exclude-members": "__weakref__",
+}
+
+# -- sphinx.ext.intersphinx config -------------------------------------------
+# For linking to power-grid-model's documentation.
+intersphinx_mapping = {"power-grid-model": ("https://power-grid-model.readthedocs.io/en/stable/", None)}

docs/index.md

@@ -0,0 +1,43 @@
+<!--
+SPDX-FileCopyrightText: 2022 Contributors to the Power Grid Model project <[email protected]>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+```{warning}
+The documentation is under heavy development
+```
+
+# Power Grid Model IO
+
+```{image} images/pgm-logo-color.svg
+:alt: pgm_logo
+:width: 150px
+:align: right
+```
+
+Power Grid Model IO is a tool to convert grid data to and from the native data format of [power-grid-model](https://github.com/alliander-opensource/power-grid-model).
+Currently, conversions from Vision and Gaia excel exports is possible. Pandapower conversions are under development.
+
+
+Detailed contents of the documentation are structured as follows.
+
+```{toctree}
+:caption: "Installation"
+:maxdepth: 2
+quickstart.md
+```
+
+```{toctree}
+:caption: "Converters"
+:maxdepth: 2
+converters/converter.md
+converters/tabular_converter.md
+```
+
+```{toctree}
+:caption: "API Documentation"
+:maxdepth: 4
+power_grid_model_io
+```
+

docs/power_grid_model_io.md

@@ -0,0 +1,60 @@
+<!--
+SPDX-FileCopyrightText: 2022 Contributors to the Power Grid Model project <[email protected]>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# power_grid_model_io
+
+## cli
+
+```{eval-rst}
+.. automodule:: power_grid_model_io.cli.convert
+.. automodule:: power_grid_model_io.cli.validate
+```
+
+## converters
+
+```{eval-rst}
+.. automodule:: power_grid_model_io.converters.base_converter
+.. automodule:: power_grid_model_io.converters.tabular_converter
+.. automodule:: power_grid_model_io.converters.gaia_excel_converter
+.. automodule:: power_grid_model_io.converters.vision_excel_converter
+.. automodule:: power_grid_model_io.converters.pgm_json_converter
+```
+
+## data_stores
+
+```{eval-rst}
+.. automodule:: power_grid_model_io.data_stores.base_data_store
+.. automodule:: power_grid_model_io.data_stores.excel_file_store
+.. automodule:: power_grid_model_io.data_stores.gaia_excel_file_store
+.. automodule:: power_grid_model_io.data_stores.json_file_store
+.. automodule:: power_grid_model_io.data_stores.vision_excel_file_store
+```
+
+## data_types
+
+```{eval-rst}
+.. automodule:: power_grid_model_io.data_types.tabular_data
+```
+
+## filters
+
+```{eval-rst}
+.. automodule:: power_grid_model_io.filters.phase_to_phase
+```
+## mappings
+
+```{eval-rst}
+.. automodule:: power_grid_model_io.mappings.tabular_mapping
+.. automodule:: power_grid_model_io.mappings.unit_mapping
+.. automodule:: power_grid_model_io.mappings.value_mapping
+```
+
+## utils
+
+```{eval-rst}
+.. automodule:: power_grid_model_io.utils.auto_id
+.. automodule:: power_grid_model_io.utils.modules
+```

pyproject.toml

@@ -46,12 +46,21 @@ dev = [
     "pytest-cov",
     "pydantic", # Used in unit tests
 ]
+doc = [
+    "sphinx",
+    "myst-parser",
+    "sphinx_rtd_theme",
+    "readthedocs-sphinx-search",
+    "sphinx-hoverxref",
+    "numpydoc",
+]
 cli = [
     "typer[all]",
 ]
 
 [project.urls]
 Home-page = "https://github.com/alliander-opensource/power-grid-model-io"
+Documentation = "https://power-grid-model-io.readthedocs.io/en/stable/"
 
 [project.scripts]
 pgm_convert = "power_grid_model_io.cli.convert:app"