From 62284279a4982db4867f37f3bd77c830897ceee2 Mon Sep 17 00:00:00 2001 From: Talley Lambert Date: Mon, 18 Dec 2023 13:14:12 -0500 Subject: [PATCH] docs: add sphinx docs (#51) * docs: add sphinx docs * fix lint * fix manifest --- .github/workflows/publish-docs.yaml | 58 +++++++++++++++++++++++++++++ .gitignore | 2 + MANIFEST.in | 1 + docs/Makefile | 20 ++++++++++ docs/api.rst | 9 +++++ docs/conf.py | 38 +++++++++++++++++++ docs/index.rst | 16 ++++++++ docs/make.bat | 35 +++++++++++++++++ ilpy/expressions.py | 2 +- ilpy/wrapper.pyx | 8 ++-- pyproject.toml | 5 +++ 11 files changed, 189 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/publish-docs.yaml create mode 100644 docs/Makefile create mode 100644 docs/api.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml new file mode 100644 index 0000000..19918b3 --- /dev/null +++ b/.github/workflows/publish-docs.yaml @@ -0,0 +1,58 @@ +name: Deploy Docs to GitHub Pages + +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: + +# Allow this job to clone the repo and create a page deployment +permissions: + contents: read + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + defaults: + run: + shell: bash -l {0} + steps: + - uses: actions/checkout@v4 + - uses: conda-incubator/setup-miniconda@v3 + with: + python-version: "3.11" + miniforge-version: latest + use-mamba: true + channels: conda-forge,gurobi,defaults + channel-priority: true + + - name: Install package and dependencies + run: | + mamba install scip gurobi + python -m pip install -e .[docs] + + - name: Build documentation + run: sphinx-build docs docs/_build/html -W -b html + + - name: Upload Pages Artifact + uses: actions/upload-pages-artifact@v2 + with: + path: docs/_build/html + retention-days: 90 + + deploy: + if: github.ref == 'refs/heads/main' + needs: build + # Deploy to the github-pages environment + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v3 diff --git a/.gitignore b/.gitignore index 24b06bf..7b326f4 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,5 @@ dist .vscode coverage.xml coverage_cpp.xml +docs/_build/ +docs/build/ \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in index dfcd53a..46b6922 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -8,3 +8,4 @@ exclude .gitmodules exclude ilpy/wrapper.cpp exclude Makefile exclude .pre-commit-config.yaml +exclude docs/* diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..b0216db --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,9 @@ +API Reference +======================= + +.. automodule:: ilpy + :members: + :undoc-members: + :private-members: + :special-members: __init__ + :show-inheritance: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..47e1430 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,38 @@ +# 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 = "ilpy" +copyright = "2023, Jan Funke, Talley Lambert" +author = "Jan Funke, Talley Lambert" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx_autodoc_typehints", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", +] +autodoc_default_options = { + "members": True, + "undoc-members": True, + "private-members": True, + "special-members": "__init__", + "show-inheritance": True, +} +intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)} + +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 = "sphinx_rtd_theme" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..07855c0 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,16 @@ +Welcome to ilpy's documentation! +================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/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/ilpy/expressions.py b/ilpy/expressions.py index f62aa15..9b44da6 100644 --- a/ilpy/expressions.py +++ b/ilpy/expressions.py @@ -19,7 +19,7 @@ class Expression(ast.AST): write ``2 * Variable('x') - Variable('y') >= 0``. Tip: you can use ``ast.dump`` to see the AST representation of an expression. - Or, use ``print(expr)` to see the string representation of an expression. + Or, use ``print(expr)`` to see the string representation of an expression. """ def as_constraint(self) -> Constraint: diff --git a/ilpy/wrapper.pyx b/ilpy/wrapper.pyx index e13d356..a5d4051 100644 --- a/ilpy/wrapper.pyx +++ b/ilpy/wrapper.pyx @@ -10,7 +10,7 @@ from . cimport decl from typing import Iterable, Mapping, Sequence if TYPE_CHECKING: - from .expression import Expression + from .expressions import Expression # no-cython-lint #################################### # Enums # @@ -227,7 +227,7 @@ cdef class Constraints: def clear(self): self.p.clear() - def add(self, constraint: Constraint | Expression): + def add(self, constraint: Constraint | "Expression"): cdef Constraint const if hasattr(constraint, "as_constraint"): const = constraint.as_constraint() @@ -261,7 +261,7 @@ cdef class Solver: self.num_variables = num_variables deref(self.p).initialize(num_variables, default_variable_type, vtypes) - def set_objective(self, objective: Objective | Expression): + def set_objective(self, objective: Objective | "Expression"): cdef Objective obj if hasattr(objective, "as_objective"): obj = objective.as_objective() @@ -272,7 +272,7 @@ cdef class Solver: def set_constraints(self, Constraints constraints): deref(self.p).setConstraints(constraints.p[0]) - def add_constraint(self, constraint: Constraint | Expression): + def add_constraint(self, constraint: Constraint | "Expression"): cdef Constraint const if hasattr(constraint, "as_constraint"): const = constraint.as_constraint() diff --git a/pyproject.toml b/pyproject.toml index cf3da6b..608a0cd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -29,6 +29,11 @@ dev = [ "numpy", "gurobipy", # used on CI to confirm equality of results ] +docs = [ + "sphinx", + "sphinx_rtd_theme", + "sphinx-autodoc-typehints", +] [project.urls] homepage = "https://github.com/funkelab/ilpy"