First release candidate of talkgooder

Signed-off-by: Brian Warner <[email protected]>

.github/CODEOWNERS

@@ -0,0 +1 @@
+*   @brianwarner

.github/workflows/lint-and-test.yml

@@ -0,0 +1,35 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Lint and test
+
+on: push
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The project default is 100 char lines
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=100 --statistics
+    - name: Test with pytest
+      run: |
+        pytest

.github/workflows/pre-release.yml

@@ -0,0 +1,42 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Build and generate documentation
+
+on: push
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install build setuptools setuptools-scm sphinx sphinx_rtd_theme myst_parser
+    - name: Build the packages
+      run: |
+        python -m build
+    - name: Generate documentation
+      run: |
+        sphinx-build -b html docsrc docs -E -d "docsrc/_doctrees"
+    - name: Check if any new docs were built
+      id: verify_diff
+      run: |
+        git diff --quiet . || echo "changed=true" >> $GITHUB_OUTPUT
+    - name: Commit and push the new documentation
+      if: steps.verify_diff.outputs.changed == 'true'
+      run: |
+        git config user.name "Brian Warner (autocommit)"
+        git config user.email [email protected]
+        git add docs
+        git commit -s -m "Rebuild the documentation"
+        git push

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI and update documentation
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install build setuptools setuptools-scm sphinx sphinx_rtd_theme myst_parser
+    - name: Build the packages
+      run: |
+        python -m build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+    - name: Generate documentation with latest version
+      run: |
+        sphinx-build -b html docsrc docs -E -d "docsrc/_doctrees"
+    - name: Check if any new docs were built
+      id: verify_diff
+      run: |
+        git diff --quiet . || echo "changed=true" >> $GITHUB_OUTPUT
+    - name: Commit and push the new documentation
+      if: steps.verify_diff.outputs.changed == 'true'
+      run: |
+        git config user.name Documentation builder[bot]
+        git config user.email [email protected]
+        git add docs
+        git commit -m "Rebuild the documentation"
+        git push

.vscode/.markdownlint.yaml

@@ -0,0 +1,5 @@
+MD013: false # Line length
+MD033: false # Inline HTML
+gitignore: true
+ignores:
+  - "CODEOWNERS"

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-python.flake8",
+        "ms-python.black-formatter",
+        "davidanson.vscode-markdownlint"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "flake8.args": [
+        "--max-line-length=100"
+    ],
+    "flake8.ignorePatterns": [
+        ".venv/*"
+    ],
+    "python.REPL.enableREPLSmartSend": false,
+    "python.terminal.activateEnvInCurrentTerminal": true,
+    "python.createEnvironment.contentButton": "show",
+    "editor.formatOnSave": true,
+}

DEVELOPING.md

@@ -0,0 +1,22 @@
+# Developing `talkgooder`
+
+`talkgooder` is as simple as possible, given the complexities of language. It initially targets `en-US` rules, but can be easily extended for other locales. PRs welcome!
+
+## Local development
+
+VS Code is recommended. Install the recommended extensions and use the default Extension settings defined in the repo.
+
+`talkgooder` has no dependencies for users, but you will need some things to develop locally. Create a venv using `requirements-dev.txt`.
+
+### Use pytest early and often
+
+Two rules:
+
+1. All functionality must be in a function
+1. All functions must have exhaustive tests
+
+Create a new test file in `tests/` for each function you add. If you add a language conditional in a function, ensure your tests cover all corner cases.
+
+### Lint your code
+
+If you aren't using VS Code, configure Flake8 and Black to run with a line length of 100.

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Brian Warner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,10 @@
+clean:
+
+	rm -rf \
+	__pycache__ \
+	src/talkgooder/__pycache__ \
+	.pytest_cache \
+	dist \
+	_version.py \
+	src/*.egg-info \
+	docsrc/_doctrees

README.md

@@ -0,0 +1,15 @@
+# Talk Gooder
+
+`talkgooder` attempts to smooth out grammar, punctuation, and number-related corner cases when formatting text for human consumption. It is intended for applications where you know there's a noun and are trying to generate text, but you don't know much about it.
+
+It handles:
+
+* Plurals
+* Possessives
+* Numbers to words
+* "There is" vs. "There are"
+* "A" vs. "An"
+
+``talkgooder`` is currently specific to American English, but it is extensible to other languages.
+
+Contributions are welcome at [github.com/brianwarner/talkgooder](https://github.com/brianwarner/talkgooder)!

docsrc/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    ?= -E -d "_doctrees"
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = ../docs
+
+# 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) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docsrc/_static/style.css

@@ -0,0 +1,36 @@
+@import 'agogo.css';
+
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+    white-space: normal;
+}
+
+
+span.sig-name.descname {
+    margin-right: .25em;
+}
+
+span.sig-return-icon {
+    margin: 0px .5em;
+}
+
+dt.sig.sig-object.py {
+    width: 100%;
+    margin-bottom: 20px !important;
+}
+
+/*
+dl.py.function dd {
+    margin-top: 20px;
+    margin-bottom: 30px;
+}
+
+*/
+dl.field-list {
+    margin-top: 20px;
+
+}
+
+dl.field-list.simple dt {
+    padding-left: 0px !important;
+}

docsrc/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+<link href="{{ pathto(" _static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}

docsrc/conf.py

@@ -0,0 +1,25 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src/talkgooder"))
+sys.path.insert(0, os.path.abspath(".."))
+
+from _version import __version__ as version  # noqa E402, must update path before use
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "myst_parser",
+]
+
+project = "talkGooder"
+copyright = "2024, Brian Warner"
+author = "Brian Warner"
+release = version
+
+html_theme = "sphinx_rtd_theme"
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+html_static_path = ["_static"]

docsrc/index.rst

@@ -0,0 +1,33 @@
+.. talkGooder documentation master file, created by
+   sphinx-quickstart on Thu Oct  3 22:58:08 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+
+
+talkGooder documentation
+========================
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+Functions
+---------
+
+.. autosummary::
+   :nosignatures:   
+
+   talkgooder.aAn :no-index:
+   talkgooder.isAre :no-index:
+   talkgooder.num2word :no-index:
+   talkgooder.plural :no-index:
+   talkgooder.possessive :no-index:
+
+-----
+
+.. automodule:: talkgooder
+    :members:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

docsrc/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=../docs
+set SPHINXOPTS=-E -d "doctrees"
+
+%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% -b %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd