From c3323e19dc77b71877d1ca70bf95a9512aa6950a Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Fri, 21 Feb 2025 11:46:28 +0100
Subject: [PATCH] clean up documentation and docstrings. Disable sphinx
nitpicky mode. Have docs CI task fail on sphinx warnings.
---
.gitlab-ci.yml | 3 ++-
docs/source/conf.py | 6 ++++--
docs/source/usage/api_modelling.md | 1 +
noxfile.py | 17 +++++++++++-----
src/pystencilssfg/composer/basic_composer.py | 1 +
src/pystencilssfg/config.py | 4 ++--
src/pystencilssfg/generator.py | 2 +-
src/pystencilssfg/ir/call_tree.py | 13 ++++--------
src/pystencilssfg/ir/entities.py | 4 ++--
src/pystencilssfg/lang/expressions.py | 21 +++++---------------
10 files changed, 34 insertions(+), 38 deletions(-)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 41e3a70..2cf8e74 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -53,10 +53,11 @@ build-documentation:
stage: "Documentation"
needs: []
script:
- - nox --session docs
+ - nox -s docs -- --fail-on-warnings
artifacts:
paths:
- docs/build/html
+ when: always
pages:
image: alpine:latest
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9b6dcf4..ecfaaef 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -38,7 +38,6 @@ extensions = [
templates_path = ["_templates"]
exclude_patterns = []
master_doc = "index"
-nitpicky = True
# -- Options for HTML output -------------------------------------------------
@@ -71,7 +70,10 @@ default_role = "any"
autodoc_member_order = "bysource"
autodoc_typehints = "description"
-# autodoc_class_signature = "separated"
+# autodoc_type_aliases = {
+# "VarLike": "pystencilssfg.lang.expressions.VarLike",
+# "ExprLike": "pystencilssfg.lang.expressions.ExprLike"
+# }
# Doctest Setup
diff --git a/docs/source/usage/api_modelling.md b/docs/source/usage/api_modelling.md
index 4ba552a..cfb0e10 100644
--- a/docs/source/usage/api_modelling.md
+++ b/docs/source/usage/api_modelling.md
@@ -235,4 +235,5 @@ expr, lang.depends(expr), lang.includes(expr)
:::{admonition} To Do
+Write guide on field data structure reflection
:::
diff --git a/noxfile.py b/noxfile.py
index a725b7b..e4f8b95 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -13,11 +13,7 @@ def add_pystencils_git(session: nox.Session):
pystencils_dir = cache_dir / "pystencils"
if pystencils_dir.exists():
with session.chdir(pystencils_dir):
- session.run_install(
- "git",
- "pull",
- external=True
- )
+ session.run_install("git", "pull", external=True)
else:
session.run_install(
"git",
@@ -76,7 +72,18 @@ def testsuite(session: nox.Session):
def docs(session: nox.Session):
"""Build the documentation pages"""
editable_install(session, ["docs"])
+
+ env = {}
+
+ session_args = session.posargs
+ if "--fail-on-warnings" in session_args:
+ env["SPHINXOPTS"] = "-W --keep-going"
+
session.chdir("docs")
+
+ if "--clean" in session_args:
+ session.run("make", "clean", external=True)
+
session.run("make", "html", external=True)
diff --git a/src/pystencilssfg/composer/basic_composer.py b/src/pystencilssfg/composer/basic_composer.py
index 6a7802f..49b6c73 100644
--- a/src/pystencilssfg/composer/basic_composer.py
+++ b/src/pystencilssfg/composer/basic_composer.py
@@ -1,4 +1,5 @@
from __future__ import annotations
+
from typing import Sequence, TypeAlias
from abc import ABC, abstractmethod
import sympy as sp
diff --git a/src/pystencilssfg/config.py b/src/pystencilssfg/config.py
index 3b63f4f..bbe2389 100644
--- a/src/pystencilssfg/config.py
+++ b/src/pystencilssfg/config.py
@@ -52,7 +52,7 @@ class OutputMode(Enum):
"""Generate only a header file.
At the moment, header-only mode does not support generation of kernels and requires that all functions
- and methods are marked `inline`.
+ and methods are marked ``inline``.
"""
@@ -64,7 +64,7 @@ class CodeStyle(ConfigBase):
"""The number of spaces successively nested blocks should be indented with"""
includes_sorting_key: BasicOption[Callable[[HeaderFile], Any]] = BasicOption()
- """Key function that will be used to sort `#include` statements in generated files.
+ """Key function that will be used to sort ``#include`` statements in generated files.
Pystencils-sfg will instruct clang-tidy to forego include sorting if this option is set.
"""
diff --git a/src/pystencilssfg/generator.py b/src/pystencilssfg/generator.py
index 5094403..91a124a 100644
--- a/src/pystencilssfg/generator.py
+++ b/src/pystencilssfg/generator.py
@@ -29,7 +29,7 @@ class SourceFileGenerator:
sfg_config: Inline configuration for the code generator
keep_unknown_argv: If `True`, any command line arguments given to the generator script
that the `SourceFileGenerator` does not understand are stored in
- `sfg.context.argv`.
+ `sfg.context.argv <SfgContext.argv>`.
"""
def _scriptname(self) -> str:
diff --git a/src/pystencilssfg/ir/call_tree.py b/src/pystencilssfg/ir/call_tree.py
index 4cee2f5..24a315d 100644
--- a/src/pystencilssfg/ir/call_tree.py
+++ b/src/pystencilssfg/ir/call_tree.py
@@ -18,13 +18,6 @@ class SfgCallTreeNode(ABC):
For extensibility, code printing is implemented inside the call tree.
Therefore, every instantiable call tree node must implement the method `get_code`.
By convention, the string returned by `get_code` should not contain a trailing newline.
-
- ## Branching Structure
-
- The branching structure of the call tree is managed uniformly through the `children` interface
- of SfgCallTreeNode. Each subclass must ensure that access to and modification of
- the branching structure through the `children` property and the `child` and `set_child`
- methods is possible, if necessary by overriding the property and methods.
"""
def __init__(self) -> None:
self._includes: set[HeaderFile] = set()
@@ -50,7 +43,7 @@ class SfgCallTreeNode(ABC):
class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
"""A leaf node of the call tree.
- Leaf nodes must implement `required_parameters` for automatic parameter collection.
+ Leaf nodes must implement ``depends`` for automatic parameter collection.
"""
def __init__(self):
@@ -69,7 +62,7 @@ class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
class SfgEmptyNode(SfgCallTreeLeaf):
"""A leaf node that does not emit any code.
- Empty nodes must still implement `required_parameters`.
+ Empty nodes must still implement ``depends``.
"""
def __init__(self):
@@ -304,6 +297,8 @@ class SfgBranch(SfgCallTreeNode):
class SfgSwitchCase(SfgCallTreeNode):
DefaultCaseType = NewType("DefaultCaseType", object)
+ """Sentinel type representing the ``default`` case."""
+
Default = DefaultCaseType(object())
def __init__(self, label: str | SfgSwitchCase.DefaultCaseType, body: SfgSequence):
diff --git a/src/pystencilssfg/ir/entities.py b/src/pystencilssfg/ir/entities.py
index b582262..40abb14 100644
--- a/src/pystencilssfg/ir/entities.py
+++ b/src/pystencilssfg/ir/entities.py
@@ -62,7 +62,7 @@ class SfgCodeEntity:
class SfgNamespace(SfgCodeEntity):
"""A C++ namespace.
- Each namespace has a `name` and a `parent`; its fully qualified name is given as
+ Each namespace has a name and a parent; its fully qualified name is given as
``<parent.name>::<name>``.
Args:
@@ -78,7 +78,7 @@ class SfgNamespace(SfgCodeEntity):
def get_entity(self, qual_name: str) -> SfgCodeEntity | None:
"""Find an entity with the given qualified name within this namespace.
- If `qual_name` contains any qualifying delimiters ``::``,
+ If ``qual_name`` contains any qualifying delimiters ``::``,
each component but the last is interpreted as a namespace.
"""
tokens = qual_name.split("::", 1)
diff --git a/src/pystencilssfg/lang/expressions.py b/src/pystencilssfg/lang/expressions.py
index d0b4978..67bd3eb 100644
--- a/src/pystencilssfg/lang/expressions.py
+++ b/src/pystencilssfg/lang/expressions.py
@@ -1,4 +1,5 @@
from __future__ import annotations
+
from typing import Iterable, TypeAlias, Any, cast
from itertools import chain
from abc import ABC, abstractmethod
@@ -13,19 +14,6 @@ from ..exceptions import SfgException
from .headers import HeaderFile
from .types import strip_ptr_ref, CppType, CppTypeFactory, cpptype
-__all__ = [
- "SfgVar",
- "AugExpr",
- "CppClass",
- "VarLike",
- "ExprLike",
- "asvar",
- "depends",
- "IFieldExtraction",
- "SrcField",
- "SrcVector",
-]
-
class SfgVar:
"""C++ Variable.
@@ -98,7 +86,7 @@ class DependentExpression:
Args:
expr: C++ Code string of the expression
- depends: Iterable of variables and/or `AugExpr`s from which variable and header dependencies are collected
+ depends: Iterable of variables and/or `AugExpr` from which variable and header dependencies are collected
includes: Iterable of header files which this expression additionally depends on
"""
@@ -374,8 +362,9 @@ def cppclass(
):
"""
Convience class decorator for CppClass.
- It adds to the decorate class the variable `template` via `lang.cpptype`
- and sets `lang.CppClass` as a base clase.
+ It adds to the decorated class the variable ``template`` via `cpptype`
+ and sets `CppClass` as a base clase.
+
>>> @cppclass("MyClass", "MyClass.hpp")
... class MyClass:
... pass
--
GitLab