docs(docs): add Sphinx support

Minimum working sphinx build. Some areas (namely testing) need expanded documentation. This also adds a code of conduct and a guide for contributing.

.gitignore

@@ -7,4 +7,6 @@ scratch.py
 .python-version
 .prql-history.txt
 *.db
+.DS_store
+docs/_build
 Session.vim*

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+# Defaults to 3.7 which doesn't support using defaults for typing
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement email at
+rb.patterson.cross@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing
+
+````{admonition} TLDR
+:class: tip
+
+Create a virtual environment with your preferred tool.
+Then run `pre-commit install --install-hooks`.
+Then commit with `cz commit`,
+and everything should take care of itself!
+````
+
+Welcome, friend!
+Open-source software isn't open open-source without the community.
+We appreciate your interest and welcome all contributions.
+While your here,
+we respectfully ask that you abide by our [code of conduct](./coc.md).
+To help keep everything moving smoothly,
+we have a few guidelines.
+
+## Bugs
+
+If you think you've found a bug,
+let us know [here][issues].
+We'll do our best to deal with it ASAP,
+but please be patient as we also work many other projects!
+
+## Developing
+
+If you think you can fix one of the bugs,
+or would like to submit a new feature,
+then let's get coding!
+
+Once you've cloned the repository,
+fork it,
+and get your development environment set up.
+We use [poetry][poetry],
+[nox][nox],
+and [pre-commit][pre-commit]
+to handle environments, testing, and linting.
+Between them,
+they make sure that all checks run in isolated environments.
+If you don't have `poetry`,
+please see the installation instructions [here][poetry_install].
+Once you have poetry,
+you can get set up with:
+
+```{code-block} shell
+poetry install
+poetry run pre-commit install --install-hooks
+```
+
+Now,
+you don't even have to think about linting or testing.
+When you commit a change,
+pre-commit will automatically run [black][black],
+[isort][isort],
+[mypy][mypy],
+and a suite of [flake8][flake8]-based linters.
+When you push a change,
+github actions will trigger a more robust suit using Nox,
+including security check and automated documentation building.
+
+### Commits
+
+We use a GitHub action for
+[python-semantic-release][psr]
+to manage our version numbers.
+This automatically parses your commit messages to determine if a new release is nesessary,
+and, if so, what kind (ie. major, minor, patch).
+So your commit message is very important!
+
+But we also don't want you stressing about how to format your commit message.
+To that end,
+we use a python implementation of
+[commitizen][cz]
+to handle that for you!
+Just commit using `cz commit` instead of `git commit`,
+and enjoy the magic!
+
+### Documentation and Testing
+
+Speaking of documentation and testing -
+if you add new code,
+please add documentation and tests for it as well.
+We use [napoleon numpy][docstrings]
+for our docstrings,
+and [sphinx][sphinx] for automatic documentation.
+Our testing suite is [pytest][pytest].
+
+## Review
+
+Once your happy with your code,
+open a pull-request,
+and we will reveiw ASAP.
+If you pull-request is not passing on github actions,
+or something else confuses us
+(we are, after all, only human!),
+we might ask for some small changes.
+Once everything is looking good,
+we will merges in your changes!
+
+## From the Command-Line
+
+```{admonition} :fireworks: Optional fun!
+
+None of this section is required, but we find it useful and hope you do, too!
+```
+
+If you haven't heard of it already,
+give a peek to to [gh][gh],
+GitHub's official CLI.
+It allows to manage all of the above steps from the command-line,
+from forking,
+to raising issues,
+and checking on the status of your pull request.
+Not a necessity,
+but for you terminal warriors out there,
+it just might help!
+
+[issues]: https://github.com/qorrect/pyprql/issues "Issues"
+[gh]: https://github.com/cli/cli "GH CLI"
+[poetry]: https://python-poetry.org/ "Poetry"
+[poetry_install]: https://python-poetry.org/docs/#installation "Poetry Installation Instructions"
+[nox]: https://nox.thea.codes/en/stable/ "Nox"
+[pre-commit]: https://pre-commit.com/ "Pre-commit"
+[black]: https://github.com/psf/black "Black"
+[isort]: https://pycqa.github.io/isort/ "iSort"
+[mypy]: https://mypy.readthedocs.io/en/stable/index.html "Mypy"
+[flake8]: https://flake8.pycqa.org/en/latest/ "Flake8"
+[psr]: https://github.com/relekang/python-semantic-release "Python Semantic Release"
+[cz]: https://commitizen-tools.github.io/commitizen/index.html "Commitizen"
+[docstrings]: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html "Numpy Napoleon Docstrings"
+[sphinx]: https://www.sphinx-doc.org/en/master/index.html "Sphinx"
+[pytest]: https://docs.pytest.org/en/7.0.x/ "pytest"

docs/assets.md

@@ -0,0 +1,14 @@
+# Assets
+
+This module contains no code.
+Rather,
+it contains a number of text files in which we store various information used by the CLI.
+
+Currently,
+there are 5 files:
+
+1. `cli_bottom_toolbar.txt`: the help message in the bottom bar of the CLI.
+1. `cli_usage.txt`: the help messages printed when the CLI is run with no arguments.
+1. `examples.txt`: some example PRQL queries.
+1. `prql_mode_help.txt`: help printed in the CLI when in `prql` mode.
+1. `sql_mode_help.txt`: help printed in the CLI when in `sql` mode.

docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

docs/cli.md

@@ -0,0 +1,25 @@
+# The Command Line Interface
+
+In addition to providing the main entrypoint,
+documented below,
+this module also documents
+the [CLI class](./cli_class.md),
+the [completer class](./completer.md),
+the [lexer class](./lexer.md),
+and the [styler class](./styler.md).
+
+```{eval-rst}
+.. automodule:: pyprql.cli
+   :members:
+   :private-members:
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 3
+
+cli_class
+completer
+lexer
+styler
+```

docs/cli_class.md

@@ -0,0 +1,7 @@
+# The CLI Class
+
+```{eval-rst}
+.. automodule:: pyprql.cli.cli
+   :members:
+   :private-members:
+```

docs/coc.md

@@ -0,0 +1,2 @@
+```{include} ../CODE_OF_CONDUCT.md
+```

docs/completer.md

@@ -0,0 +1,7 @@
+# The prompt-toolkit Completer
+
+```{eval-rst}
+.. automodule:: pyprql.cli.PRQLCompleter
+   :members:
+   :private-members:
+```

docs/conf.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+"""Sphinx configuration."""
+import os
+import sys
+
+import sphinx_rtd_theme
+
+sys.path.insert(0, os.path.abspath("../"))
+sys.path.insert(0, os.path.abspath("../pyprql/"))
+
+project = "PyPRQL"
+author = "Charlie Sando"
+copyright = "2022, Charlie Sando"
+version = "0.4.1"
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+]
+
+napoleon_google_docstrings = False
+napoleon_numpy_docstrings = True
+napoleon_use_param = False
+
+html_theme = "sphinx_rtd_theme"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+myst_heading_anchors = 2

docs/contributing.md

@@ -0,0 +1,2 @@
+```{include} ../CONTRIBUTING.md
+```