Added initial docs (#180)

Added initial docs

.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

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.
 

dev-requirements.txt

@@ -1,4 +1,5 @@
 ruff==0.6.2
 build
 pytest-cov
-mypy>=1.0.0
+mypy>=1.0.0
+Sphinx

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)

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

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",
+}

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 <https://pypi.org/project/pyswip/>`_.
+
+.. TIP::
+    We recommend installing PySwip into a Python virtual environment.
+    See: `Creation of virtual environments <https://docs.python.orgs/3/library/venv.html>`_
+
+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 <https://www.swi-prolog.org/Download.html>`_ 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 <https://brew.sh>`_.
+
+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)")))
+
+

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 <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.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   get_started
+