From d46eef266ed3fb2e40f72ad4ac596d935130449e Mon Sep 17 00:00:00 2001 From: Jean-Didier Garaud Date: Fri, 24 Jan 2025 16:03:19 +0100 Subject: [PATCH 1/2] Start a doc --- python/doc/Makefile | 20 +++++++++++ python/doc/make.bat | 35 +++++++++++++++++++ python/doc/source/conf.py | 58 +++++++++++++++++++++++++++++++ python/doc/source/index.rst | 26 ++++++++++++++ python/doc/source/reference.rst | 60 +++++++++++++++++++++++++++++++++ python/requirements.txt | 14 ++++++++ 6 files changed, 213 insertions(+) create mode 100644 python/doc/Makefile create mode 100644 python/doc/make.bat create mode 100644 python/doc/source/conf.py create mode 100644 python/doc/source/index.rst create mode 100644 python/doc/source/reference.rst create mode 100644 python/requirements.txt diff --git a/python/doc/Makefile b/python/doc/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/python/doc/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) diff --git a/python/doc/make.bat b/python/doc/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/python/doc/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 diff --git a/python/doc/source/conf.py b/python/doc/source/conf.py new file mode 100644 index 0000000..9c81440 --- /dev/null +++ b/python/doc/source/conf.py @@ -0,0 +1,58 @@ +# 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 = 'CutCells' +copyright = '2024, ONERA' +author = 'Susanne Claus' +release = '0.2.0' +import cutcells + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.imgmath', + 'sphinx.ext.autosummary', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinx_copybutton', +# "autoapi.extension", + ] + +templates_path = ['_templates'] +exclude_patterns = [] + +# Napoleon settings +napoleon_google_docstring = True +napoleon_numpy_docstring = False + +autoclass_content = 'both' # this concatenates the class.doc + __init__.doc +autodoc_typehints = "description" # typehints are nicely placed + +todo_include_todos = True +todo_link_only = True + +# alternatively, could use autoapi: +# # autoapi coonfiguration: +# package_dir = next(x for x in nanobind_example.__path__ if "site-packages" in x) +# autoapi_dirs = [f"{package_dir}/"] +# # https://github.com/readthedocs/sphinx-autoapi/issues/405 +# #autoapi_ignore = ["*__init__.py*"] +# autoapi_member_order = "groupwise" +# # autoapi_generate_api_docs = False + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +#html_theme = 'furo' +html_theme = 'nature' +html_static_path = ['_static'] diff --git a/python/doc/source/index.rst b/python/doc/source/index.rst new file mode 100644 index 0000000..570dc2f --- /dev/null +++ b/python/doc/source/index.rst @@ -0,0 +1,26 @@ +.. nanobind_example documentation master file, created by + sphinx-quickstart on Tue Dec 17 14:55:35 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +cutcells documentation +====================== + +To build this module and documentation:: + + pip install . && ( cd doc; make html; ) + + +.. todo:: + + Complete requirements.txt + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + reference + + +.. todolist:: diff --git a/python/doc/source/reference.rst b/python/doc/source/reference.rst new file mode 100644 index 0000000..a8e171e --- /dev/null +++ b/python/doc/source/reference.rst @@ -0,0 +1,60 @@ +================== + Module reference +================== + +.. sidebar:: Version information + + :Release: |release| + :Date: |today| + +.. contents:: + :local: + + + +Nanobind autosummary example +**************************** + +.. currentmodule:: cutcells +.. autosummary:: + + CellType + CutCell_float32 + + +Cutcells automodule example +*************************** + +The module provides ... + +.. automodule:: cutcells + :members: + :imported-members: + :undoc-members: + :show-inheritance: + +.. todo:: + + * cleanup the doc + + +Cutcells autofunction example +***************************** + +.. comment + no-index are in this section because it'd make duplicates with the previous section + +Explicitly asking for the doc of a specific function works: + +.. autofunction:: cutcells.cut + :no-index: + + +.. note:: + + I could write something here. + + + + +.. literalinclude:: /../../demo/cut_triangle/cut_triangle.py diff --git a/python/requirements.txt b/python/requirements.txt new file mode 100644 index 0000000..d335110 --- /dev/null +++ b/python/requirements.txt @@ -0,0 +1,14 @@ +# surely +numpy +nanobind + +scikit_build_core +Sphinx +sphinx-autoapi +sphinx-autodoc-typehints +sphinx-copybutton +sphinx_design +sphinx_mdinclude + +# maybe +typing_extensions From ee214ce54040c7eabb0467142466797ff62d3b67 Mon Sep 17 00:00:00 2001 From: Jean-Didier Garaud Date: Fri, 24 Jan 2025 16:16:01 +0100 Subject: [PATCH 2/2] Add sphinx tips --- python/doc/source/index.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/python/doc/source/index.rst b/python/doc/source/index.rst index 570dc2f..31feada 100644 --- a/python/doc/source/index.rst +++ b/python/doc/source/index.rst @@ -24,3 +24,24 @@ To build this module and documentation:: .. todolist:: + + + + +.. note:: + + Some feedback about Sphinx + + These are nice Cheat Sheets for reST format to use with Sphinx: + + - `Restructured Text (reST) and Sphinx CheatSheet `_ + + - `Sphinx and RST syntax guide `_ + + - `reStructuredText specifications `_ and its `abridged version `_ + + Docstrings Google Style is recommended to document the module: + + - `sphinx.ext.napoleon documentation `_ + + - `Google style docstring examples `_