From 5985ccb66cb1d3b41f9e8ee5cd8b4308e07f3329 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 14:38:40 +0000 Subject: [PATCH 01/12] Python docs --- .github/workflows/docs.yml | 31 ++++++- python/docs/Makefile | 19 ++++ python/docs/conf.py | 180 +++++++++++++++++++++++++++++++++++++ python/docs/index.rst | 11 +++ 4 files changed, 237 insertions(+), 4 deletions(-) create mode 100644 python/docs/Makefile create mode 100644 python/docs/conf.py create mode 100644 python/docs/index.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8e701df..6455f92 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,6 +11,12 @@ jobs: name: Build docs runs-on: ubuntu-latest steps: + - name: Install LAPACK, OpenBLAS + run: sudo apt-get install -y libopenblas-dev liblapack-dev + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.14" - name: Set up Rust uses: actions-rust-lang/setup-rust-toolchain@v1 with: @@ -20,22 +26,39 @@ jobs: with: mpi: "mpich" - uses: actions/checkout@v4 - - - name: Build docs + - name: Build Rust docs run: cargo +nightly doc --no-deps -Zunstable-options -Zrustdoc-scrape-examples --all-features - - name: Set file permissions run: | rm target/doc/.lock chmod -c -R +rX target/doc + - name: Install uv + run: pip install uv "maturin>=1.7" + - name: Make virtual environment + run: | + uv venv .venv + uv pip install pip pytest + - name: Build python docs + run: | + cd python/docs + make html + + - name: Move docs + run: | + mkdir doc + mv target/doc doc/rust + mkdir python/docs/html/_build doc/python + - name: Make index page + run: echo "ndelement docs
Rust docs
Python docs
" > doc/index.html + - name: Setup Pages uses: actions/configure-pages@v3 if: github.ref == 'refs/heads/main' - name: Upload artifact for docs uses: actions/upload-pages-artifact@v3 with: - path: 'target/doc' + path: 'doc' if: github.ref == 'refs/heads/main' deploy-docs: diff --git a/python/docs/Makefile b/python/docs/Makefile new file mode 100644 index 0000000..5128596 --- /dev/null +++ b/python/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +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 + +# 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) diff --git a/python/docs/conf.py b/python/docs/conf.py new file mode 100644 index 0000000..e058003 --- /dev/null +++ b/python/docs/conf.py @@ -0,0 +1,180 @@ +"""Configuration file for the Sphinx documentation builder. + +This file does only contain a selection of the most common options. For a +full list see the documentation: +http://www.sphinx-doc.org/en/master/config +""" + +# -- 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 os +import sys +import toml as tomllib + +sys.path.insert(0, os.path.abspath("..")) + + +# -- Project information ----------------------------------------------------- + +project = "ndelement" +copyright = "2022-, Matthew Scroggs" +author = "Matthew Scroggs" + +with open("../../pyproject.toml") as f: + version = tomllib.load(f)["project"]["version"] + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.mathjax", + "autoapi.extension", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" + +# The master toctree document. +master_doc = "index" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# 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"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- 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 = "sphinxdoc" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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"] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "ndelementdoc" + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + "papersize": "a4paper", + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, "ndelement.tex", "ndelement Documentation", "Matthew Scroggs", "manual"), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "ndelement", "ndelement Documentation", [author], 1)] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "ndelement", + "ndelement Documentation", + author, + "ndelement", + "Python interface to Rust finite element definition library", + "Miscellaneous", + ), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ["search.html"] + + +# -- Extension configuration ------------------------------------------------- +autoapi_type = "python" +autoapi_dirs = ["../ndelement"] +autoapi_root = "docs" diff --git a/python/docs/index.rst b/python/docs/index.rst new file mode 100644 index 0000000..2b57c19 --- /dev/null +++ b/python/docs/index.rst @@ -0,0 +1,11 @@ +========= +ndelement +========= + +Welcome to the documention of ndelement. + +Documentation index +=================== + +.. toctree:: + :titlesonly: From a80caf6f4009b2a541beb2e05b61a9a196b0fa2e Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 14:40:25 +0000 Subject: [PATCH 02/12] spaces --- .github/workflows/docs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6455f92..daa7c6e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -14,9 +14,9 @@ jobs: - name: Install LAPACK, OpenBLAS run: sudo apt-get install -y libopenblas-dev liblapack-dev - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: "3.14" + uses: actions/setup-python@v4 + with: + python-version: "3.14" - name: Set up Rust uses: actions-rust-lang/setup-rust-toolchain@v1 with: From 036bf81e9a69b62a0621326d9ca3769e73d9f531 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 14:49:54 +0000 Subject: [PATCH 03/12] tomllib --- .github/workflows/docs.yml | 2 +- python/docs/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index daa7c6e..c224538 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -50,7 +50,7 @@ jobs: mv target/doc doc/rust mkdir python/docs/html/_build doc/python - name: Make index page - run: echo "ndelement docs
Rust docs
Python docs
" > doc/index.html + run: echo "ndelement docs
Rust docs
Python docs
" > doc/index.html - name: Setup Pages uses: actions/configure-pages@v3 diff --git a/python/docs/conf.py b/python/docs/conf.py index e058003..a96910a 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -13,7 +13,7 @@ # import os import sys -import toml as tomllib +import tomllib sys.path.insert(0, os.path.abspath("..")) From 78a3e00a67cb8cb54f813a6bc0ef3b8e0d2ef6e9 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 14:50:54 +0000 Subject: [PATCH 04/12] index page --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c224538..0b6be35 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -28,6 +28,8 @@ jobs: - uses: actions/checkout@v4 - name: Build Rust docs run: cargo +nightly doc --no-deps -Zunstable-options -Zrustdoc-scrape-examples --all-features + - name: Make index page + run: echo "" > target/doc/index.html - name: Set file permissions run: | rm target/doc/.lock From 46c3840408fb5f2a81ae723f4728cc704c75a05e Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 19:24:04 +0000 Subject: [PATCH 05/12] rb, add badge --- README.md | 1 + python/docs/conf.py | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f6e262..704e51d 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ [![DefElement verification](https://defelement.org/badges/ndelement.svg)](https://defelement.org/verification/ndelement.html) [![crates.io](https://img.shields.io/crates/v/ndelement)](https://crates.io/crates/ndelement) [![docs.rs](https://img.shields.io/docsrs/ndelement?label=docs.rs)](https://docs.rs/ndelement/latest/ndelement/) +[![PyPI](https://img.shields.io/pypi/v/ndelement?color=blue&label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/ndelement/) ndelement is an open-source library written in Rust that can be used to create n-dimensional finite elements. diff --git a/python/docs/conf.py b/python/docs/conf.py index a96910a..0c2983c 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -24,7 +24,7 @@ copyright = "2022-, Matthew Scroggs" author = "Matthew Scroggs" -with open("../../pyproject.toml") as f: +with open("../../pyproject.toml", "rb") as f: version = tomllib.load(f)["project"]["version"] From 83d91b00017c96dadabf8826d10da40cbc225a04 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 19:24:49 +0000 Subject: [PATCH 06/12] make crates.io blue --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 704e51d..0906016 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # ndelement [![DefElement verification](https://defelement.org/badges/ndelement.svg)](https://defelement.org/verification/ndelement.html) -[![crates.io](https://img.shields.io/crates/v/ndelement)](https://crates.io/crates/ndelement) +[![crates.io](https://img.shields.io/crates/v/ndelement?color=blue)](https://crates.io/crates/ndelement) [![docs.rs](https://img.shields.io/docsrs/ndelement?label=docs.rs)](https://docs.rs/ndelement/latest/ndelement/) [![PyPI](https://img.shields.io/pypi/v/ndelement?color=blue&label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/ndelement/) From c2a58fd77612336a07ba992ba2392e6c68d1e977 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 19:37:38 +0000 Subject: [PATCH 07/12] requirements.txt --- .github/workflows/docs.yml | 25 ++++++++++++------------- python/docs/requirements.txt | 1 + 2 files changed, 13 insertions(+), 13 deletions(-) create mode 100644 python/docs/requirements.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0b6be35..ebe9d9e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -26,24 +26,23 @@ jobs: with: mpi: "mpich" - uses: actions/checkout@v4 - - name: Build Rust docs - run: cargo +nightly doc --no-deps -Zunstable-options -Zrustdoc-scrape-examples --all-features - - name: Make index page - run: echo "" > target/doc/index.html - - name: Set file permissions - run: | - rm target/doc/.lock - chmod -c -R +rX target/doc + #- name: Build Rust docs + # run: cargo +nightly doc --no-deps -Zunstable-options -Zrustdoc-scrape-examples --all-features + #- name: Make index page + # run: echo "" > target/doc/index.html + #- name: Set file permissions + # run: | + # rm target/doc/.lock + # chmod -c -R +rX target/doc - name: Install uv - run: pip install uv "maturin>=1.7" - - name: Make virtual environment + run: pip install uv + - name: Build Python docs run: | uv venv .venv - uv pip install pip pytest - - name: Build python docs - run: | + uv pip install pip cd python/docs + uv pip install -r requirements.txt make html - name: Move docs diff --git a/python/docs/requirements.txt b/python/docs/requirements.txt new file mode 100644 index 0000000..44a988d --- /dev/null +++ b/python/docs/requirements.txt @@ -0,0 +1 @@ +sphinx-autoapi From bca8cd804ca7cbaaee592b0c4f295441aee96fb0 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 19:45:02 +0000 Subject: [PATCH 08/12] install sphinx --- python/docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/python/docs/requirements.txt b/python/docs/requirements.txt index 44a988d..68736ef 100644 --- a/python/docs/requirements.txt +++ b/python/docs/requirements.txt @@ -1 +1,2 @@ +sphinx sphinx-autoapi From 1c2fa289aeafb156cb3f51077f34383f6dff7391 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 19:52:33 +0000 Subject: [PATCH 09/12] activate venv --- .github/workflows/docs.yml | 5 ++++- pyproject.toml | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ebe9d9e..ff2ac20 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -37,10 +37,13 @@ jobs: - name: Install uv run: pip install uv - - name: Build Python docs + - name: Make virtual environment run: | uv venv .venv uv pip install pip + - name: Build Python docs + run: | + source .venv/bin/activate cd python/docs uv pip install -r requirements.txt make html diff --git a/pyproject.toml b/pyproject.toml index 3752ff3..d477925 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,6 +27,7 @@ packages = ["ndelement"] [project.urls] homepage = "https://github.com/bempp/ndelement" repository = "https://github.com/bempp/ndelement" +documentation = "https://bempp.github.io/ndelement/python" [tool.maturin] python-source = "python" From 25ed84958fb142ba3745b08027534d6984a0b7d1 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Tue, 4 Nov 2025 20:00:19 +0000 Subject: [PATCH 10/12] uncomment --- .github/workflows/docs.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ff2ac20..0c33134 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -26,14 +26,14 @@ jobs: with: mpi: "mpich" - uses: actions/checkout@v4 - #- name: Build Rust docs - # run: cargo +nightly doc --no-deps -Zunstable-options -Zrustdoc-scrape-examples --all-features - #- name: Make index page - # run: echo "" > target/doc/index.html - #- name: Set file permissions - # run: | - # rm target/doc/.lock - # chmod -c -R +rX target/doc + - name: Build Rust docs + run: cargo +nightly doc --no-deps -Zunstable-options -Zrustdoc-scrape-examples --all-features + - name: Make index page + run: echo "" > target/doc/index.html + - name: Set file permissions + run: | + rm target/doc/.lock + chmod -c -R +rX target/doc - name: Install uv run: pip install uv From 3b6f3f525c9a2131fd1cf33d42f8da6a13b182ef Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Wed, 5 Nov 2025 10:00:48 +0000 Subject: [PATCH 11/12] mv not mkdir --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0c33134..122793f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -52,7 +52,7 @@ jobs: run: | mkdir doc mv target/doc doc/rust - mkdir python/docs/html/_build doc/python + mv python/docs/html/_build doc/python - name: Make index page run: echo "ndelement docs
Rust docs
Python docs
" > doc/index.html From 9ec3f50a240691e875b3fb88e11daaffe6af3f38 Mon Sep 17 00:00:00 2001 From: Matthew Scroggs Date: Wed, 5 Nov 2025 10:10:39 +0000 Subject: [PATCH 12/12] folder name --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 122793f..67d25f5 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -52,7 +52,7 @@ jobs: run: | mkdir doc mv target/doc doc/rust - mv python/docs/html/_build doc/python + mv python/docs/_build/html doc/python - name: Make index page run: echo "ndelement docs
Rust docs
Python docs
" > doc/index.html