🚀 Add sphinx and deploy to readthedocs.io (#13)

* 🚀 Add sphinx and deploy to readthedocs.io

* ✏️ Add newer python  classifiers

* 🐛 Amend docs.txt for 3.6+

* 🚨 Run pytest on src and tests only

* 🐛 Amend ci.txt for 3.6+

* 🐛 Explicitly point to tests/

* 🐛 Unpin pytest

.github/workflows/main.yml

@@ -2,76 +2,89 @@ name: GH
 
 on:
   pull_request:
-    branches: '*'
   push:
-    branches: 'master'
-    tags: '*'
+    branches: master
+  release:
+    types: [released, prereleased]
+  workflow_dispatch:  # allows running workflow manually from the Actions tab
 
 jobs:
   CI:
     runs-on: ubuntu-latest
     strategy:
-      max-parallel: 8
       matrix:
-        python-version: [2.7, 3.5, 3.6, 3.7, 3.8]
+        python-version: ['2.7', '3.5', '3.6', '3.7', '3.8', '3.9', '3.10', '3.11']
     steps:
     - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
 
     - name: Pip cache
       uses: actions/cache@v2
       with:
         path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements/*.txt') }}
+        key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('**/requirements/*.txt') }}
         restore-keys: |
           ${{ runner.os }}-pip-
 
-    - run: pip install -U pip setuptools wheel
+    - name: Pre-commit cache
+      uses: actions/cache@v2
+      with:
+        path: ~/.cache/pre-commit
+        key: ${{ runner.os }}-pre-commit-${{ matrix.python-version }}-${{ hashFiles('**/requirements/ci.txt') }}-${{ hashFiles('.pre-commit-config.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pre-commit-
 
     - name: Install dependencies
-      run: make install
+      run: |
+        pip install -U pip setuptools wheel codecov
+        make install
 
     - name: Lint
-      if: matrix.python-version == 3.8
+      if: matrix.python-version == 3.11
       run: make lint
 
     - name: Test
       run: make test
 
+    - name: Docs
+      if: matrix.python-version == 3.11
+      run: SPHINXOPTS=-W make builddocs
+
     - name: Codecov
-      if: matrix.python-version == 3.8
       env:
         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
       run: |
-        pip install codecov
         codecov
 
   CD:
     needs: CI
-    if: startsWith(github.ref, 'refs/tags/')
+    if: github.event_name == 'release'
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
 
-    - name: Set up Python 3.8
+    - name: Set up Python
       uses: actions/setup-python@v2
       with:
-        python-version: 3.8
+        python-version: 3.x
 
-    - name: PyPi Deploy preparation
+    - name: Build
       run: |
-        pip install --upgrade setuptools wheel
+        pip install -U pip setuptools wheel twine
         python setup.py sdist bdist_wheel --universal
 
-    - name: PyPi Deploy
-      uses: pypa/[email protected]
-      with:
-        user: ${{ secrets.PYPI_USER }}
-        password: ${{ secrets.PYPI_PASSWORD }}
+    - name: Publish
+      env:
+        TWINE_USERNAME: ${{ secrets.PYPI_USER }}
+        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+      run: |
+        twine upload dist/*
 
     - uses: apexskier/github-release-commenter@v1
       with:

.gitignore

@@ -1,2 +1,6 @@
+# docs
+docs/source/README.md
+docs/source/_code_reference/
+
 # setuptools_scm
 _repo_version.py

.pre-commit-config.yaml

@@ -1,45 +1,61 @@
 repos:
 -   repo: https://github.com/Yelp/detect-secrets
-    rev: v1.2.0
+    rev: v1.4.0
     hooks:
     -   id: detect-secrets
         args: ['--baseline', '.secrets.baseline']
         exclude: .*/tests/.*
 
 -   repo: https://github.com/psf/black
-    rev: 22.3.0
+    # when updating this version, also update blacken-docs hook below
+    rev: 22.10.0
     hooks:
     -   id: black
 
+-   repo: https://github.com/asottile/blacken-docs
+    rev: v1.12.1
+    hooks:
+    -   id: blacken-docs
+        additional_dependencies: ['black==22.10.0']
+
 -   repo: https://github.com/timothycrosley/isort
     rev: 5.10.1
     hooks:
     -   id: isort
 
+-   repo: local
+    hooks:
+    -   id: mypy
+        name: Run mypy
+        entry: python -m mypy src/
+        language: system
+        types: [python]
+        pass_filenames: false
+
 -   repo: https://github.com/PyCQA/flake8
-    rev: 4.0.1
+    rev: 5.0.4
     hooks:
     -   id: flake8
         additional_dependencies: [
-            # 'darglint~=1.5.4',
+            # 'darglint~=1.8.1',
             'flake8-absolute-import~=1.0',
             'flake8-blind-except~=0.2.1',
-            'flake8-builtins~=1.5.3',
+            'flake8-builtins~=2.0.1',
             'flake8-cognitive-complexity==0.1.0',
-            'flake8-comprehensions~=3.8.0',
-            # 'flake8-docstrings~=1.5.0',
-            'flake8-logging-format~=0.6.0',
+            'flake8-comprehensions~=3.10.0',
+            # 'flake8-docstrings~=1.6.0',
+            'flake8-logging-format~=0.8.1',
             'flake8-mutable~=1.2.0',
-            'flake8-print~=4.0.0',
-            'flake8-printf-formatting~=1.1.2',
+            'flake8-print~=5.0.0',
+            'flake8-printf-formatting~=1.1.0',
             'flake8-pytest-style~=1.6.0',
             'flake8-quotes~=3.3.1',
             'flake8-tuple~=0.4.1',
-            'pep8-naming~=0.12.1'
+            'pep8-naming~=0.13.2'
         ]
 
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.1.0
+    rev: v4.3.0
     hooks:
     -   id: mixed-line-ending
         args: ['--fix=lf']
@@ -50,3 +66,11 @@ repos:
     -   id: check-toml
     -   id: check-xml
     -   id: check-yaml
+    -   id: debug-statements
+
+-   repo: https://github.com/econchick/interrogate
+    rev: 1.5.0
+    hooks:
+      - id: interrogate
+        pass_filenames: false
+        args: [-c, setup.cfg]

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.8
+  install:
+    - method: pip
+      path: .
+    - requirements: requirements/docs.txt

Makefile

@@ -8,13 +8,27 @@ lint:
 test:
 	python -m pytest tests/
 
+.PHONY: showcov
+## Open the test coverage overview using the default HTML viewer
+showcov:
+	xdg-open htmlcov/index.html || open htmlcov/index.html
+
 .PHONY: install
-## Install for development
+## Install this repo, plus dev requirements, in editable mode
 install:
-	pip install -r requirements/ci.txt
-	pip install -e .
+	pip install -r requirements/ci.txt -r requirements/docs.txt -e .
 	pre-commit install || true  # not installed on older python versions
 
+.PHONY: builddocs
+## Build documentation using Sphinx
+builddocs:
+	cd docs && make docs
+
+.PHONY: showdocs
+## Open the docs using the default HTML viewer
+showdocs:
+	xdg-open docs/_build/html/index.html || open docs/_build/html/index.html
+
 .PHONY: help
 ## Print Makefile documentation
 help:

README.md

@@ -45,7 +45,11 @@ $ pip install retrie
 
 ## Usage
 
-The following objects are all subclasses of [`retrie.retrie.Retrie`](src/retrie/retrie.py), which handles filling the Trie and compiling the corresponding regex pattern.
+[![readthedocs](https://readthedocs.org/projects/retrie/badge/?version=latest)](https://retrie.readthedocs.io)
+
+For documentation, see [retrie.readthedocs.io](https://retrie.readthedocs.io/en/stable/_code_reference/retrie.html).
+
+The following objects are all subclasses of `retrie.retrie.Retrie`, which handles filling the Trie and compiling the corresponding regex pattern.
 
 
 #### Blacklist

docs/Makefile

@@ -0,0 +1,29 @@
+
+# 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)
+
+show:
+	xdg-open docs/_build/html/index.html || open docs/_build/html/index.html
+
+docs:
+	rm -rf source/_code_reference
+	make clean
+	make html