docs: Add infrastructure for publishing documentation

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: docs
+on:
+  push:
+  pull_request:
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - uses: actions/checkout@v3
+      - run: python -m pip install .[docs]
+      - run: python -m sphinx -W -b html docs/ build/html/
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: build/html
+
+  deploy:
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master'
+    steps:
+      - uses: actions/deploy-pages@v1

docs/conf.py

@@ -0,0 +1,27 @@
+project = 'beanquery'
+copyright = '2014-2022, beanquery Contributors'
+author = 'beanquery Contributors'
+version = '0.1'
+language = 'en'
+html_theme = 'furo'
+html_title = f'{project} {version}'
+html_logo = 'logo.svg'
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.githubpages',
+]
+extlinks = {
+    'issue': ('https://github.com/beancount/beanquery/issues/%s', '#'),
+    'pull': ('https://github.com/beancount/beanquery/pull/%s', '#'),
+}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'beancount': ('https://beancount.github.io/docs/', None),
+}
+napoleon_google_docstring = True
+napoleon_use_param = False
+autodoc_typehints = 'none'
+autodoc_member_order = 'bysource'

docs/index.rst

@@ -0,0 +1,7 @@
+beanquery: Customizable lightweight SQL query tool
+==================================================
+
+beanquery is a customizable and extensible lightweight SQL query tool
+that works on tabular data, including `Beancount`__ ledger data.
+
+__ https://beancount.github.io/

docs/logo.inkscape

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   width="512"
+   height="512"
+   version="1.1"
+   id="svg56"
+   sodipodi:docname="icon.svg"
+   inkscape:version="1.2.1 (9c6d41e4, 2022-07-14)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs60" />
+  <sodipodi:namedview
+     id="namedview58"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     showgrid="false"
+     inkscape:zoom="0.89155981"
+     inkscape:cx="348.82685"
+     inkscape:cy="232.17736"
+     inkscape:window-width="1309"
+     inkscape:window-height="838"
+     inkscape:window-x="0"
+     inkscape:window-y="23"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="svg56" />
+  <rect
+     fill="#0067a5"
+     x="40"
+     y="40"
+     width="432"
+     height="432"
+     rx="30"
+     id="rect48"
+     style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-opacity:1;stroke-width:3;stroke-dasharray:none" />
+  <g
+     stroke-linejoin="bevel"
+     stroke-linecap="square"
+     fill="none"
+     id="g54">
+    <path
+       d="M282.702 317.017c0 21.566-6.99 40.13-20.958 55.703-13.966 15.575-32.116 25.2-54.463 28.863v37.042c0 1.964-.61 3.648-1.88 4.91-1.26 1.264-2.87 1.965-4.84 1.965h-28.44c-1.82 0-3.39-.56-4.73-1.964-1.33-1.263-2-2.947-2-4.77v-37.043c-9.26-1.263-18.22-3.367-26.85-6.454-8.7-3.09-15.86-6.18-21.47-9.41-5.61-3.09-10.81-6.46-15.58-10.11-4.77-3.65-8.14-6.32-9.82-8-1.82-1.69-2.95-2.95-3.65-3.79-2.38-2.95-2.52-5.9-.42-8.7l21.62-28.49c.99-1.4 2.53-2.25 4.78-2.53 2.11-.28 3.79.42 5.06 1.96l.42.42c15.87 14.03 32.85 22.87 51.1 26.52 5.198 1.12 10.39 1.68 15.58 1.68 11.37 0 21.34-2.95 30.04-8.98 8.56-6.03 12.918-14.59 12.918-25.68 0-3.93-1.122-7.72-3.227-11.228-2.105-3.504-4.49-6.45-7.16-8.84s-6.736-5.05-12.35-7.854c-5.615-2.946-10.25-5.19-13.9-6.735-3.65-1.68-9.262-3.93-16.842-6.876l-13.054-5.33c-3.225-1.26-7.58-3.09-13.05-5.61-5.476-2.39-9.83-4.63-13.197-6.46s-7.3-4.35-11.93-7.44c-4.63-3.09-8.42-6.033-11.23-8.98-2.946-2.86-5.894-6.314-9.123-10.383-3.23-3.93-5.755-8.05-7.44-12.207-1.824-4.17-3.23-8.84-4.49-14.03-.84-5.61-1.405-11.08-1.405-16.84 0-19.5 6.88-36.48 20.636-51.21 13.758-14.73 32.006-24.593 54.04-28.802V73.21c0-1.824.7-3.41 1.996-4.77 1.36-1.263 2.95-1.965 4.77-1.965h28.48c1.97 0 3.57.63 4.83 1.908 1.265 1.263 1.897 2.89 1.897 4.855v37.183c8 .85 15.72 2.49 23.16 4.87 7.44 2.39 13.62 4.77 18.25 7.09 4.63 2.33 9.124 4.97 13.335 7.93 4.21 2.95 6.88 5.01 8.14 6.13 1.263 1.12 2.246 2.11 3.09 2.95 2.384 2.56 2.665 5.24.98 8.06l-16.99 30.87c-1.12 2.11-2.807 3.23-4.91 3.37-1.966.57-3.93 0-5.756-1.4-.42-.42-1.407-1.26-3.09-2.52s-4.35-3.09-8.28-5.61c-3.93-2.38-8-4.63-12.356-6.73-4.35-1.96-9.686-3.79-15.72-5.47-6.18-1.54-12.074-2.39-17.97-2.39-13.335 0-24.283 3.09-32.706 9.12-8.42 6.18-12.63 13.89-12.63 23.58 0 3.65.56 7.02 1.82 10.107 1.12 3.08 3.23 6.03 6.18 8.84s5.75 5.05 8.28 7.01 6.48 4.07 11.79 6.598c5.22 2.525 9.47 4.35 12.7 5.75 3.23 1.26 8.14 3.228 14.74 5.75 7.44 2.81 13.194 5.055 17.124 6.738s9.262 4.07 16 7.437c6.735 3.365 12.07 6.31 15.86 8.98 3.93 2.664 8.28 6.17 13.054 10.66 4.91 4.35 8.56 8.84 11.23 13.33 2.665 4.63 4.84 9.96 6.67 16.276 1.82 6.174 2.71 12.91 2.71 19.925l.66-.674"
+       fill="#fff"
+       id="path50"
+       style="fill:#0067a5;fill-opacity:1" />
+    <path
+       d="M229.305 317.017c0 21.566 6.99 40.13 20.957 55.703 13.967 15.575 32.116 25.2 54.463 28.863v37.042c0 1.964.618 3.648 1.88 4.91 1.265 1.264 2.88 1.965 4.844 1.965h28.43c1.82 0 3.39-.56 4.73-1.964 1.33-1.263 2.01-2.947 2.01-4.77v-37.043c9.26-1.263 18.22-3.367 26.85-6.454 8.7-3.09 15.86-6.18 21.47-9.41 5.61-3.09 10.81-6.46 15.58-10.11 4.77-3.65 8.14-6.32 9.82-8 1.82-1.69 2.94-2.95 3.65-3.79 2.38-2.95 2.52-5.9.42-8.7l-21.61-28.48c-.98-1.4-2.53-2.25-4.77-2.53-2.11-.28-3.79.42-5.06 1.96l-.43.42c-15.86 14.03-32.85 22.87-51.1 26.52-5.2 1.12-10.39 1.68-15.58 1.68-11.37 0-21.34-2.95-30.04-8.98-8.57-6.04-12.92-14.6-12.92-25.68 0-3.93 1.12-7.72 3.23-11.23 2.1-3.51 4.49-6.46 7.16-8.84s6.74-5.05 12.35-7.86c5.61-2.95 10.24-5.19 13.89-6.74 3.65-1.686 9.26-3.93 16.84-6.878l13.055-5.33c3.23-1.26 7.58-3.084 13.052-5.61 5.47-2.38 9.82-4.63 13.19-6.45s7.3-4.35 11.93-7.44c4.63-3.09 8.42-6.034 11.23-8.98 2.95-2.863 5.89-6.315 9.12-10.384 3.23-3.923 5.752-8.05 7.44-12.2 1.82-4.17 3.23-8.84 4.49-14.03s1.823-10.72 1.823-16.5c0-19.39-6.88-36.48-20.635-51.11-13.753-14.62-31.86-24.418-53.9-28.628V73.35c0-1.824-.7-3.437-1.964-4.77-1.96-1.403-3.51-2.105-5.33-2.105H311.4c-1.962 0-3.534.63-4.8 1.908-1.26 1.263-1.893 2.89-1.893 4.855v37.183c-8.003.85-15.75 2.49-23.26 4.87-7.51 2.39-13.617 4.77-18.333 7.09-4.72 2.33-9.17 4.97-13.39 7.93-4.215 2.95-6.95 5.01-8.216 6.13-1.27 1.12-2.3 2.11-3.15 2.95-2.387 2.56-2.737 5.24-1.053 8.06l17.07 30.87c1.12 2.11 2.734 3.23 4.84 3.37 1.962.57 3.93 0 5.752-1.4.42-.42 1.4-1.26 3.085-2.52s4.35-3.09 8.28-5.61c3.79-2.38 7.86-4.63 12.21-6.73 4.35-1.96 9.545-3.79 15.72-5.47 6.037-1.54 12.073-2.39 17.97-2.39 13.334 0 24.14 3.09 32.564 9.12 8.426 6.18 12.637 13.89 12.637 23.58 0 3.65-.56 7.02-1.824 10.11-1.26 3.088-3.37 6.03-6.32 8.84-2.95 2.807-5.76 5.05-8.42 7.016s-6.6 4.07-11.79 6.6c-5.34 2.524-9.55 4.35-12.78 5.75-3.23 1.26-8.14 3.227-14.74 5.75-7.44 2.81-13.19 5.054-17.13 6.737s-9.26 4.07-16 7.437c-6.74 3.362-12.07 6.31-16 8.98-3.93 2.66-8.14 6.17-13.06 10.66-4.77 4.35-8.56 8.84-11.09 13.33-2.665 4.63-4.91 9.96-6.736 16.273-1.824 6.174-2.81 12.91-2.81 19.925l.56-.673"
+       fill="#a6c4da"
+       id="path52" />
+  </g>
+</svg>

pyproject.toml

@@ -38,6 +38,12 @@ dependencies = [
     'tatsu >= 5.7.4, < 5.8.0',
 ]
 
+[project.optional-dependencies]
+docs = [
+    'furo >= 2024.08.06',
+    'sphinx ~= 8.1.0',
+]
+
 [project.scripts]
 bean-query = 'beanquery.shell:main'