diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 00000000..bd281ca0 --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,43 @@ +name: Build Docs + +on: + push: + branches: + - main + workflow_dispatch: # Make sure this job can be triggered manually + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: read + pages: write + id-token: write + steps: + - uses: actions/checkout@v5 + - uses: actions/configure-pages@v3 + - uses: actions/setup-python@v5 + with: + python-version: '3.13' + - name: Install dependencies + run: | + cd quaddtype/ + python -m pip install --upgrade pip + python -m pip install "numpy @ git+https://github.com/numpy/numpy.git" pytest meson meson-python + - name: Build quaddtype package + run: | + cd quaddtype/ + python -m pip install . -v --no-build-isolation + - name: Build Sphinx documentation + run: | + cd quaddtype/ + python -m pip install ."[docs]" + cd docs/ + sphinx-build -b html . _build/html/quaddtype + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 + with: + path: './quaddtype/docs/_build/html' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 721680c2..9919bea9 100644 --- a/.gitignore +++ b/.gitignore @@ -143,3 +143,6 @@ compile_commands.json /quaddtype/subprojects/sleef/ /quaddtype/subprojects/pythoncapi-compat/ .wraplock + +# docs +/quaddtype/docs/_build/ diff --git a/quaddtype/README.md b/quaddtype/README.md index d6b854e2..c3dd655b 100644 --- a/quaddtype/README.md +++ b/quaddtype/README.md @@ -25,7 +25,7 @@ np.array([1,2,3], dtype=QuadPrecDType("longdouble")) ## Installation from source -#### Prerequisites +### Prerequisites - **gcc/clang** - **CMake** (≥3.15) @@ -170,4 +170,37 @@ This is a development feature to help detect threading issues. To build `numpy-q export CXXFLAGS="-fsanitize=thread -g -O0" export LDFLAGS="-fsanitize=thread" python -m pip install . -vv --no-build-isolation -Csetup-args=-Db_sanitize=thread - ``` \ No newline at end of file + ``` + +## Building the documentation + +The documentation for the `numpy-quaddtype` package is built using Sphinx. To build the documentation, follow these steps: + +1. Install the required dependencies: + + ```bash + pip install ."[docs]" + ``` + +2. Navigate to the `docs` directory and build the documentation: + + ```bash + cd docs/ + make html + ``` + +3. The generated HTML documentation can be found in the `_build/html` directory within the `docs` folder. Open the `index.html` file in a web browser to view the documentation, or use a local server to serve the files: + + ```bash + python3 -m http.server --directory _build/html + ``` + +### Serving the documentation + +The documentation is automatically built and served using GitHub Pages. Every time changes are pushed to the `main` branch, the documentation is rebuilt and deployed to the `gh-pages` branch of the repository. You can access the documentation at: + +``` +https://numpy.github.io/numpy-user-dtypes/quaddtype/ +``` + +Check the `.github/workflows/build_docs.yml` file for details. diff --git a/quaddtype/docs/Makefile b/quaddtype/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/quaddtype/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 = . +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/quaddtype/docs/api_docs.rst b/quaddtype/docs/api_docs.rst new file mode 100644 index 00000000..b167a85a --- /dev/null +++ b/quaddtype/docs/api_docs.rst @@ -0,0 +1,7 @@ +NumPy QuadDType API Documentation +================================= + +.. automodule:: numpy_quaddtype + :members: + :undoc-members: + :show-inheritance: diff --git a/quaddtype/docs/conf.py b/quaddtype/docs/conf.py new file mode 100644 index 00000000..2f6243ab --- /dev/null +++ b/quaddtype/docs/conf.py @@ -0,0 +1,29 @@ +# 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 = 'NumPy QuadDType' +copyright = '2025, NumPy Community' +author = 'NumPy Community' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'myst_parser', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'pydata_sphinx_theme' + diff --git a/quaddtype/docs/index.md b/quaddtype/docs/index.md new file mode 100644 index 00000000..c19eba45 --- /dev/null +++ b/quaddtype/docs/index.md @@ -0,0 +1,8 @@ +```{include} ../README.md +``` + +```{toctree} +:hidden: + +api_docs.rst +``` diff --git a/quaddtype/docs/make.bat b/quaddtype/docs/make.bat new file mode 100644 index 00000000..954237b9 --- /dev/null +++ b/quaddtype/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=. +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/quaddtype/pyproject.toml b/quaddtype/pyproject.toml index c72b0c62..feca2441 100644 --- a/quaddtype/pyproject.toml +++ b/quaddtype/pyproject.toml @@ -37,6 +37,12 @@ test = [ "pytest-run-parallel" ] +docs = [ + "sphinx", + "pydata-sphinx-theme", + "myst-parser", +] + [project.urls] Repository = "https://github.com/numpy/numpy-user-dtypes" Documentation = "https://github.com/numpy/numpy-user-dtypes/tree/main/quaddtype"