diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..da938a7 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,10 @@ +version: 2 +build: + os: ubuntu-24.04 + tools: + python: latest +sphinx: + configuration: docs/conf.py +python: + install: + - requirements: dev-requirements.txt \ No newline at end of file diff --git a/README.md b/README.md index 1e7ad37..c2ffb5f 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ See [Get Started](https://pyswip.org/get-started.html) for detailed instructions ## Introduction -PySwip is a Python - SWI-Prolog bridge enabling to query [SWI-Prolog](http://www.swi-prolog.org) in your Python programs. -It features an (incomplete) SWI-Prolog foreign language interface, a utility class that makes it easy querying with Prolog and also a Pythonic interface. +PySwip is a Python-Prolog interface that enables querying [SWI-Prolog](https://www.swi-prolog.org) in your Python programs. +It features an SWI-Prolog foreign language interface, a utility class that makes it easy querying with Prolog and also a Pythonic interface. Since PySwip uses SWI-Prolog as a shared library and ctypes to access it, it doesn't require compilation to be installed. diff --git a/dev-requirements.txt b/dev-requirements.txt index 8911de3..23f9a6a 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -1,4 +1,5 @@ ruff==0.6.2 build pytest-cov -mypy>=1.0.0 \ No newline at end of file +mypy>=1.0.0 +Sphinx \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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 = 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/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..dc1312a --- /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=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/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..658bd40 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,37 @@ +# 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 = "PySwip" +copyright = "2024, Yüce Tekol and PySwip Contributors" +author = "Yüce Tekol and PySwip Contributors" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.duration", + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "myst_parser", +] + +templates_path = ["_templates"] +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "alabaster" +html_static_path = ["_static"] + +source_suffix = { + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", +} diff --git a/docs/source/get_started.rst b/docs/source/get_started.rst new file mode 100644 index 0000000..2b16f3f --- /dev/null +++ b/docs/source/get_started.rst @@ -0,0 +1,163 @@ +Get Started +=========== + +Requirements +------------ + +* Python 3.8 or later +* SWI-Prolog 8.4.2 or later +* 64bit Intel or ARM processor + +.. IMPORTANT:: + Make sure the SWI-Prolog architecture is the same as the Python architecture. + If you are using a 64bit build of Python, use a 64bit build of SWI-Prolog, etc. + + +Installing PySwip +----------------- + +.. _install_from_pypi: + +PyPI +^^^^ + +PySwip is available to install from `Python Package Index `_. + +.. TIP:: + We recommend installing PySwip into a Python virtual environment. + See: `Creation of virtual environments `_ + +You can install PySwip using:: + + pip install pyswip + +You will need to have SWI-Prolog installed on your system. +See :ref:`install_swi_prolog`. + +PySwip requires the location of the ``libswpl`` shared library and also the SWI-Prolog home directory. +In many cases, PySwip can find the shared library and the home directory automatically. +Otherwise, you can use the following environment variables: + +* ``SWI_HOME_DIR``: The SWI-Prolog home directory. It must contain the ``swipl.home`` file. + It's the ``$SWI_PROLOG_ROOT/lib/swipl`` directory if you have compiled SWI-Prolog form source. +* ``LIBSWIPL_PATH``: The location of the ``libswipl`` shared library. + +You can get the locations mentioned above using the following commands:: + + swipl --dump-runtime-variables + +That will output something like:: + + PLBASE="/home/yuce/swipl-9.3.8/lib/swipl"; + ... + PLLIBDIR="/home/yuce/swipl-9.3.8/lib/swipl/lib/x86_64-linux"; + +Use the value in the ``PLBASE`` variable as the value for the ``SWI_HOME_DIR`` environment variable. +Use the value in the ``PLLIBDIR`` variable as the value for the ``LIBSWIPL_PATH`` environment variable. + +Arch Linux / Manjaro Linux / Parabola GNU/Linux-libre +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These Linux distributions have PySwip in their package repositories. +You can use the following to install PySwip globally:: + + pacman -S python-pyswip + +.. NOTE:: + We recommend installing PySwip from :ref:`install_from_pypi`. + +Fedora Workstation +^^^^^^^^^^^^^^^^^^ + +You can use the following to install PySwip globally:: + + dnf install python3-pyswip + +.. NOTE:: + We recommend installing PySwip from :ref:`install_from_pypi`. + +.. _install_swi_prolog: + +Installing SWI-Prolog +--------------------- + +Some operating systems have packages for SWI-Prolog. +Otherwise, you can download it from `SWI-Prolog's website `_ or build from source. + +Arch Linux / Manjaro Linux / Parabola GNU/Linux-libre +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SWI-Prolog is available in the standard package repository:: + + pacman -S swi-prolog + +Fedora Workstation +^^^^^^^^^^^^^^^^^^ + +Installing SWI-Prolog:: + + dnf install pl + +Debian, Ubuntu, Raspbian +^^^^^^^^^^^^^^^^^^^^^^^^ + +* Ubuntu 22.04 has SWI-Prolog 8.4.3 in its repository. +* Debian Bookworm, Ubuntu 24.04 and Raspberry Pi OS Bookworm have SWI-Prolog 9.0.4 in their repositories. + +Use the following to install SWI-Prolog:: + + apt install swi-prolog-nox + + +Windows +------- + +Download a recent version of SWI-Prolog from https://www.swi-prolog.org/Download.html and install it. + +MacOS +----- + +The preferred way of installing SWI-Prolog on MacOS is using `Homebrew `_. + +Homebrew +^^^^^^^^ + +Installing SWI-Prolog:: + + brew install swi-prolog + + +Official SWI-Prolog App +^^^^^^^^^^^^^^^^^^^^^^^ + +Install SWI-Prolog from https://www.swi-prolog.org/Download.html. + +If you get an error like ``libgmp.X not found``, you have to set the ``DYLD_FALLBACK_LIBRARY_PATH`` environment variable before running Python:: + + export DYLD_FALLBACK_LIBRARY_PATH=/Applications/SWI-Prolog.app/Contents/Frameworks + +OpenBSD +------- + +Install SWI-Prolog using the following on OpenBSD 7.6 and later:: + + pkg_add swi-prolog + +FreeBSD +------- + +SWI-Prolog can be installed using ``pkg``:: + + pkg install swi-pl + +Test Drive +---------- + +Run a quick test by running following code at your Python console:: + + + from pyswip import Prolog + Prolog.assertz("father(michael,john)") + print(list(Prolog.query("father(X,Y)"))) + + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..482c9d7 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,17 @@ +.. PySwip documentation master file, created by + sphinx-quickstart on Sun Oct 13 13:18:34 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +PySwip Documentation +==================== + +PySwip is a Python-Prolog interface that enables querying `SWI-Prolog `_ in your Python programs. +It features an SWI-Prolog foreign language interface, a utility class that makes it easy querying with Prolog and also a Pythonic interface. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + get_started +