Add documentation rendering (#250)

* Add cython signatures

* Add documentation based on sphinx

* Add changelog

Author: fsimonis

.gitignore

@@ -2,6 +2,8 @@
 .idea # Pycharm related file
 *.so
 build
+docs/_build
+docs/.docs_venv
 *.egg-info
 __pycache__
 env

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## latest
+
+* Added support for documentation rendering https://github.com/precice/python-bindings/pull/250
+
 ## 3.3.1
 
 * Remove root user option from the usage of the preCICE image in the release workflow https://github.com/precice/python-bindings/commit/0a9ccd449e875f0165bebc968b3a23d6d9094b0d

docs/build.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+if [[ ! -f "../pyproject.toml" ]]; then
+  echo "Please run from the docs directory."
+  exit 1
+fi
+
+TARGET=singlehtml
+
+python3 -m venv --clear .docs_venv
+
+echo "Installing dependencies"
+.docs_venv/bin/pip install sphinx myst_parser sphinx-rtd-theme
+
+echo "Installing python bindings"
+.docs_venv/bin/pip install --force --no-cache ..
+
+echo "Building the website"
+.docs_venv/bin/sphinx-build -M ${TARGET} . _build

docs/conf.py

@@ -0,0 +1,45 @@
+# 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
+
+import datetime
+
+project = "pyprecice"
+author = "The preCICE developers"
+copyright = f"{datetime.datetime.now().year}, {author}"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "mpi4py": ("https://mpi4py.readthedocs.io/en/latest/", None),
+}
+
+# exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".docs_venv"]
+include_patterns = ["*.rst", "*.md"]
+
+html_theme = "sphinx_rtd_theme"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+autodoc_class_signature = "separated"
+autodoc_typehints = "description"
+autodoc_typehints_format = "short"
+autodoc_member_order = "bysource"
+
+suppress_warnings = ["myst.xref_missing"]
+
+# The cython detection relyies on a built and installed version of the package
+try:
+    import precice
+except:
+    raise RuntimeError("Cannot import precice. Please install pyprecice first")

docs/index.rst

@@ -0,0 +1,10 @@
+The preCICE python bindings
+===========================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   precice
+   MigrationGuide
+   ReleaseGuide

docs/precice.rst

@@ -0,0 +1,6 @@
+The pyprecice package
+=====================
+
+.. automodule:: cyprecice
+   :members:
+   :undoc-members:

setup.py

@@ -48,6 +48,7 @@ def get_extensions():
             extra_compile_args=compile_args,
             extra_link_args=link_args,
             define_macros=[("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")],
+            cython_directives={"embedsignature": True},
         )
     ]