Migrate documentation to sphinx

fixes #181  

* Add sphinx to dev dependencies
* Add furo theme
* Add sphinx-copybutton as dev dependency
* Add basic sphinx based documentation
* Add github action to generate documentation
* Bump version number to 3.1.10

.github/workflows/gh-pages.yaml

@@ -0,0 +1,37 @@
+name: GH-Pages
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "*"
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+
+      - name: Install Dependencies
+        run: |
+          poetry install
+      - name: Build Documenations
+        run: |
+          poetry run python -m nox -s build-docs
+          touch doc/build/html/.nojekyll
+      - name: Deploy
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: ./doc/build/html
+          git-config-name: Github Action
+          git-config-email: [email protected]
+

.gitignore

@@ -1,5 +1,7 @@
 odbcconfig/odbcinst.ini
 
+_build/
+
 *.py[cod]
 
 .build_output

CHANGELOG.rst

@@ -30,7 +30,8 @@
 - The support of the turbodbc feature has been suspended, until the following issues have been addressed
     * https://github.com/blue-yonder/turbodbc/issues/358
     * https://github.com/exasol/sqlalchemy-exasol/issues/146
-    Note: If you depend on turbodbc we suggest you to use the latest version supporting it (2.4.0)
+    * Note: If you depend on turbodbc we suggest you to use the latest version supporting it (2.4.0)
+
 - Dropped python 3.7 support
   * If you still depend on python 3.7 use the 2.x version line
 - Dropped conda forge support
@@ -279,7 +280,7 @@
 - Updated SQLAlchemy dependency to 1.1.13
 
 
-.. _changelog-1.3.1:
+.. _changelog-1.3.0:
 
 1.3.0 — 2017-08-02
 ===================

README.rst

@@ -135,11 +135,12 @@ Notes
 - Always use all lower-case identifiers for schema, table and column names. SQLAlchemy treats all lower-case identifiers as case-insensitive, the dialect takes care of transforming the identifier into a case-insensitive representation of the specific database (in case of EXASol this is upper-case as for Oracle)
 - As of Exasol client driver version 4.1.2 you can pass the flag 'INTTYPESINRESULTSIFPOSSIBLE=y' in the connection string (or configure it in your DSN). This will convert DECIMAL data types to Integer-like data types. Creating integers is a factor three faster in Python than creating Decimals.
 
-Development & Testing
-`````````````````````
-See `developer guide`_
-
 .. _developer guide: https://github.com/exasol/sqlalchemy-exasol/blob/master/doc/developer_guide/developer_guide.rst
 .. _odbc_driver: https://docs.exasol.com/db/latest/connect_exasol/drivers/odbc/odbc_linux.htm
 .. _test_drive: https://www.exasol.com/test-it-now/cloud/
 .. _test_docker_image: https://github.com/exasol/docker-db
+
+Development & Testing
+`````````````````````
+See `developer guide`_
+

changelog.d/20220805_130513_nicola.coretti__170_Migrate_documentation_to_sphinx.rst

@@ -0,0 +1,3 @@
+🔧 Changed
+----------
+- Restructured documentation

changelog.d/20220805_073754_nicola.coretti__166_add_scriv_to_simplify_creating_the_changelog.rst → changelog.d/20220808_101829_nicola.coretti__170_Migrate_documentation_to_sphinx.rst

@@ -14,7 +14,7 @@
 ..
 🔧 Changed
 ----------
- - Updated the developer documents to reflect the latest changelog management 
+- Reworked project documenation
 ..
 .. 🚧 Deprecated
 .. -------------

doc/changelog.rst

@@ -0,0 +1,4 @@
+Changelog
+_________
+
+.. include:: ../CHANGELOG.rst

doc/conf.py

@@ -0,0 +1,64 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+import sys
+from pathlib import Path
+
+SPHINX_ROOT = Path(__file__).parent
+sys.path.insert(0, f"{SPHINX_ROOT.parent.resolve()}")
+
+from sqlalchemy_exasol.version import VERSION
+
+# -- Project information -----------------------------------------------------
+
+project = "sqlalchemy-exasol"
+copyright = "2022, Exasol & Blue Yonder"
+author = "Exasol,  Blue Yonder"
+
+# The full version, including alpha/beta/rc tags
+release = VERSION
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx_copybutton"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+html_title = f"SQLAlchemy-Exasol {release}"
+html_theme_options = {
+    "light_logo": "light-exasol-logo.svg",
+    "dark_logo": "dark-exasol-logo.svg",
+}
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

doc/developer_guide/index.rst

@@ -0,0 +1,8 @@
+.. include:: developer_guide.rst
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   integration_tests
+

doc/index.rst

@@ -0,0 +1,46 @@
+SQLAlchemy-Exasol
+=================
+SQLAlchemy-Exasol is an SQLAlchemy dialect extension.
+
+Overview
+--------
+The dialect is the system SQLAlchemy uses to communicate with various types of DBAPI implementations and databases.
+The sections that follow contain reference documentation and notes specific to the usage of each backend,
+as well as notes for the various DBAPIs.
+
+For more details have a look into the `SQLAlchemy documentation <https://docs.sqlalchemy.org/en/13/dialects/>`_.
+
+Getting Started
+---------------
+
+#. `Install the Exasol-ODBC driver <https://docs.exasol.com/db/latest/connect_exasol/drivers/odbc.htm>`_
+
+#. Add `sqlalchemy-exasol <https://pypi.org/project/sqlalchemy-exasol/>`_ as a dependency
+
+    .. code-block:: shell
+
+        $ pip install sqlalchemy-exasol
+
+#. Execute queries
+
+    .. code-block:: python
+
+        from sqlalchemy import create_engine
+        url = "exa+pyodbc://A_USER:[email protected]:1234/my_schema?CONNECTIONLCALL=en_US.UTF-8&driver=EXAODBC"
+        e = create_engine(url)
+        r = e.execute("select 42 from dual").fetchall()
+
+
+For more details on SQLAlchemy consult it's `documenation <https://docs.sqlalchemy.org/en/13/>`_.
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+
+   readme
+   changelog
+   developer_guide/index
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/readme.rst

@@ -0,0 +1,5 @@
+Readme
+______
+
+.. include:: ../README.rst
+   :end-before: Development & Testing

noxfile.py

@@ -2,15 +2,19 @@
 
 import os
 import sys
+import webbrowser
 from argparse import ArgumentParser
 from contextlib import contextmanager
 from pathlib import Path
+from shutil import rmtree
 from tempfile import TemporaryDirectory
 from textwrap import dedent
 
 PROJECT_ROOT = Path(__file__).parent
 # scripts path also contains administrative code/modules which are used by some nox targets
 SCRIPTS = PROJECT_ROOT / "scripts"
+DOC = PROJECT_ROOT / "doc"
+DOC_BUILD = DOC / "build"
 sys.path.append(f"{SCRIPTS}")
 
 from typing import (
@@ -417,3 +421,31 @@ def create_parser() -> ArgumentParser:
         *args,
         external=True,
     )
+
+
+@nox.session(python=False, name="clean-docs")
+def clean(session: Session) -> None:
+    """Remove all documentation artifacts"""
+    if DOC_BUILD.exists():
+        rmtree(DOC_BUILD.resolve())
+        session.log(f"Removed {DOC_BUILD}")
+
+
+@nox.session(python=False, name="build-docs")
+def build(session: Session) -> None:
+    """Build the documentation"""
+    session.run(
+        "sphinx-build", "-b", "html", "-W", f"{DOC}", f"{DOC_BUILD}", external=True
+    )
+
+
+@nox.session(python=False, name="open-docs")
+def open_docs(session: Session) -> None:
+    """Open the documentation in the browser"""
+    index_page = DOC_BUILD / "index.html"
+    if not index_page.exists():
+        session.error(
+            f"File {index_page} does not exist." "Please run `nox -s build-docs` first"
+        )
+
+    webbrowser.open_new_tab(index_page.resolve().as_uri())