Create documentation (#2)

* Add documentation

* Add github actions

* Update CHANGELOG and README

.github/workflows/update_doc.yml

@@ -0,0 +1,54 @@
+name: update_doc
+
+# execute this workflow automatically on push to master
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+
+  build_docs_job:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U sphinx
+          python -m pip install sphinx-rtd-theme
+          python -m pip install sphinx-autoapi
+      - name: Install library
+        run: |
+          python -m pip install -e .    
+      - name: make the sphinx docs
+        run: |
+          make -C docs clean 
+          sphinx-apidoc -o docs/source/generated pydhn -f -t docs/source/_templates/apidoc --module-first --implicit-namespaces --separate
+          make -C docs html
+
+      - name: Init new repo in dist folder and commit generated files
+        run: |
+          cd docs/build/html/
+          git init
+          touch .nojekyll
+          git add -A
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git commit -m 'deploy'
+
+      - name: Force push to destination branch
+        uses: ad-m/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          force: true
+          directory: ./docs/build/html

.pre-commit-config.yaml

@@ -4,6 +4,7 @@ repos:
     hooks:
     - id: isort # sort imports
       args: [--sl, --profile=black]
+      files: '^((?!__init__.py).)*$'
   - repo: https://github.com/psf/black
     rev: 23.7.0
     hooks:

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Change Log
 
+## 0.1.3
+
+Released on October 30, 2024
+
+### Added
+
+* Added documentation files in /docs
+* Added a GitHub action to deploy the documentation on Pages
+
+### Changed
+
+* Improved docstrings and type hints
+* docstring_parameters now ignores curly braces outside the Parameter section of a docstring
+* Modified .pre-commit-config.yaml so that isort ignores init files to avoid circular import issues 
+* Added dependencies needed for docs to pyproject.toml 
+
+### Removed
+
+
 ## 0.1.2
 
 Released on March 19, 2024
@@ -12,6 +31,7 @@ Released on March 19, 2024
 
 ### Removed
 
+
 ## 0.1.1
 
 Released on January 19, 2024
@@ -36,4 +56,4 @@ Released on January 19, 2024
 
 Released on January 12, 2024
 
-* Initial release
+* Initial release

README.md

@@ -20,7 +20,7 @@ PyDHN is currently in a beta version, and as such, it may undergo frequent and s
 
 ## Documentation
 
-The documentation for this beta version is currently being written and is not yet available. In the meantime, the main features are explained in the provided examples (`examples/`).
+The documentation is available [here](https://idiap.github.io/pydhn/). In addition, the main features are explained in the provided examples (`examples/`).
 
 ## License
 

docs/Makefile

@@ -0,0 +1,20 @@
+# 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     = source
+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
+
+# 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)

docs/generate_apidoc.bat

@@ -0,0 +1,2 @@
+@echo off
+sphinx-apidoc -o source/generated ../pydhn -f -t source/_templates/apidoc --module-first --implicit-namespaces --separate

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=source
+set BUILDDIR=build
+
+%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.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/apidoc/module.rst_t

@@ -0,0 +1,13 @@
+{%- if show_headings %}
+{{- basename.split(".")[-1] | e | heading }}
+{% endif -%}
+
+{%- set parts = basename.split('.') %}
+{%- set library_name = parts[0] %}
+{%- set module_name = parts[1] if parts | length > 1 else '' %}
+{%- set submodules = parts[2:] %}
+
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}

docs/source/_templates/apidoc/package.rst_t

@@ -0,0 +1,59 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- pkgname.split(".")[-1] | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+
+{# Create breadcrumb navigation #}
+{%- set parts = submodule.split('.') -%}
+{%- for i in range(parts|length) %}
+{{ '[{}]({}.html)'.format(parts[i], '/'.join(parts[:i+1])) | e | heading(2) }}
+{%- endfor %}
+
+{%- endif %}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+Module contents
+---------------
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}

docs/source/_templates/apidoc/toc.rst_t

@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}

docs/source/about/references.rst

@@ -0,0 +1,15 @@
+References
+=================
+
+
+.. [HaZa21] Hafsi, Z. (2021). Accurate explicit analytical solution for Colebrook-White equation. Mechanics Research Communications, 111, p.103646. doi: https://doi.org/10.1016/j.mechrescom.2020.103646.
+
+.. [DeAl19] Dénarié, A., Aprile, M. and Motta, M. (2019). Heat transmission over long pipes: New model for fast and accurate district heating simulations. Energy, 166, pp.267–276. doi: https://doi.org/10.1016/j.energy.2018.09.186
+
+.. [CzWo98] Czeslaw Oleskowicz Popiel and Wojtkowiak, J. (1998). Simple Formulas for Thermophysical Properties of Liquid Water for Heat Transfer Calculations (from 0°C to 150°C). Heat Transfer Engineering, 19(3), pp.87–101. doi: https://doi.org/10.1080/01457639808939929.
+
+.. [RoDa03] Robinson, D. (2003) ‘CLIMATE AS A PRE-DESIGN TOOL’, in Proceedings of Building Simulation 2003: 8th Conference of IBPSA. Eindhoven, Netherlands: IBPSA (Building Simulation), pp. 1109–1116. doi: https://doi.org/10.26868/25222708.2007.1109-1116.
+
+.. [PYDHN23] Boghetti, R. and Kämpf, J.H. (2023). Verification of an open-source Python library for the simulation of district heating networks with complex topologies. Energy, [online] 290, pp.130169–130169. doi: https://doi.org/10.1016/j.energy.2023.130169.
+
+‌

docs/source/autovalue.py

@@ -0,0 +1,41 @@
+import importlib
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.statemachine import ViewList
+from sphinx.ext.autodoc import between
+from sphinx.roles import SphinxRole
+
+
+class AutoValueDirective(Directive):
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+    has_content = False
+
+    def run(self):
+        module_name, _, attr_name = self.arguments[0].rpartition(".")
+        module = importlib.import_module(module_name)
+        value = getattr(module, attr_name)
+
+        # Create a node and add the value as its content
+        node = nodes.literal(text=str(value), classes=["autovalue"])
+        return [node]
+
+
+class AutoValueRole(SphinxRole):
+    def run(self):
+        # Split the input (module and attribute)
+        module_name, _, attr_name = self.text.rpartition(".")
+        # Dynamically import the module and get the attribute value
+        module = importlib.import_module(module_name)
+        value = getattr(module, attr_name)
+
+        # Return a literal node containing the value
+        return [nodes.literal(text=str(value), classes=["autovalue"])], []
+
+
+def setup(app):
+    app.add_directive("autovalue", AutoValueDirective)
+    app.add_role("autovalue", AutoValueRole())

docs/source/conf.py

@@ -0,0 +1,59 @@
+# 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 = "PyDHN"
+copyright = (
+    "2024, Idiap Research Institute, https://www.idiap.ch, EPFL, https://www.epfl.ch"
+)
+author = "Roberto Boghetti"
+release = "0.1.2"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.napoleon",  # For Google and NumPy style docstrings
+    "sphinx.ext.viewcode",
+    # 'sphinx.ext.autosectionlabel',
+    "sphinx.ext.doctest",
+]
+
+
+templates_path = ["_templates"]
+exclude_patterns = ["generated/modules.rst"]
+doctest_test_doctest_blocks = "default"
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath("../pydhn"))
+sys.path.insert(0, os.path.abspath("."))
+
+
+import autovalue
+
+
+def skip(app, what, name, obj, would_skip, options):
+    if name == "__init__":
+        return False
+    return would_skip
+
+
+def setup(app):
+    autovalue.setup(app)
+    app.connect("autodoc-skip-member", skip)
+
+
+add_module_names = False
+
+# -- 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"]