Add Sphinx/RST-based documentation website

.github/CONTRIBUTING.rst

@@ -0,0 +1,147 @@
+So you’d like to contribute? Awesome! Here are some things worth
+knowing.
+
+Reporting a bug / requesting a feature / asking a question
+----------------------------------------------------------
+
+Go `open an issue <https://github.com/nat-n/poethepoet/issues>`_ or
+`start a discussion <https://github.com/nat-n/poethepoet/discussions>`_ and
+I’ll probably reply soon.
+
+Contributing code
+-----------------
+
+Preface
+~~~~~~~
+
+If you’re willing to contribute your ideas and effort to making poethepoet
+better, then that’s awesome and I’m grateful. I don’t have all the answers so
+it’s particularly important for this project to benefit from diverse
+perspectives and technical expertise.
+
+However please be aware that a lot of thought has gone into the architecture of
+poethepoet, and whilst I know it’s not perfect, and I am very interested in
+alternative perspectives, I do have strong (and I hope reasonable) opinions
+about how certain things should work. This particularly applies to naming and
+internal APIs. There is a lot to consider in terms of making sure the tool stays
+simple, flexible, and performant. So please don’t be offended if there is some
+push back.
+
+Development process
+~~~~~~~~~~~~~~~~~~~
+
+1. If your planned changes entail non-trivial UI or internal API changes then
+   it’s a good idea to bring them up for discussion as a
+   `GitHub issue <https://github.com/nat-n/poethepoet/issues>`_ first.
+
+2. Fork and clone the repo, and create a feature or bugfix branch off of the
+   *development* branch.
+
+3. Double check that you’re starting from the *development* branch, and not from
+   the the *main* branch.
+
+4. Run ``poetry install`` to setup your development environment.
+   (`install poetry <https://python-poetry.org/docs/#installation>`__)
+
+5. Do your code.
+
+6. If you’ve added a feature then before it can be including in a release we
+   will need:
+
+   a. a feature test along the same lines as the examples in the tests dir,
+   b. to update documentation.
+
+5. Run ``poe check`` to check that you haven’t broken anything that will
+   block the CI pipeline.
+
+6. Create a commit with a clear commit message that describes the commit
+   contents.
+
+7. Open a PR on GitHub.
+
+Pull requests
+~~~~~~~~~~~~~
+
+There isn’t currently a pull request template, but please try and be descriptive
+about what problem you’re solving and how, and reference related issues.
+
+In some cases it might be acceptable to merge code to *development* to make a
+pre-release from it without including full automated tests and documentation.
+However this is a special case, because it blocks further releases from the
+*development* branch until the tests and docs are there.
+
+Branching model
+~~~~~~~~~~~~~~~
+
+This project implements something like git flow.
+
+*TL;DR* branch off of *development* for new features, or *main* for minor bug
+fixes or doc improvements.
+
+We like to keep a clean history, so squash-rebase merges are preferred for the
+*development* or *main* branches.
+
+Overview of branches
+~~~~~~~~~~~~~~~~~~~~
+
+Historic branches
+^^^^^^^^^^^^^^^^^
+
+-  **main** the primary branch containing released code and up to date docs.
+-  **development** in progress and pre-released features that are expected to be
+   included in a release when ready.
+
+Working branches
+^^^^^^^^^^^^^^^^
+
+-  **hotfix/** branches for minor/urgent bug fixes from main
+-  **feature/** branches for new feature development from development
+-  **bugfix/** for new bug fixes from development
+-  **doc/** branches for documentation changes
+
+How to add a new feature
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Create your branch from *development*
+
+   ::
+
+      git fetch
+      git checkout origin/development
+      git checkout -b feature/my_new_feature
+
+2. Create a pull request back to *development*
+
+How to add a hot fix
+~~~~~~~~~~~~~~~~~~~~
+
+1. Create your branch from *main*
+
+   ::
+
+      git fetch
+      git checkout origin/main
+      git checkout -b feature/my_new_feature
+
+2. Create a pull request back to *main*, and one to *development*
+
+How to create pre-release
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. From the head of the *development* branch, create release commit that
+   bumps the version in ``pyproject.toml`` and ``__version__.py``
+   (there’s a test to ensure these are in sync).
+2. Create a release (and tag) on GitHub, following the existing
+   convention for naming and release notes format, and the GitHub CI
+   will do the rest.
+
+How to create release
+~~~~~~~~~~~~~~~~~~~~~
+
+1. Create a branch off of *development* like **release/1.0.0** and add a
+   commit to bump the version in ``pyproject.toml`` and
+   ``__version__.py``.
+2. Merge it into both *main* and *development*
+3. Create a GitHub release from the head of main, following the existing
+   convention for naming and release notes format, and the GitHub CI
+   will do the rest.

.github/workflows/ci.yml

@@ -31,14 +31,14 @@ jobs:
         run: poetry run poe types
 
       - name: Check rst syntax
-        run: poetry run poe check-docs
+        run: poetry run poe docs-check
 
   run-tests:
     name: Run tests
     strategy:
       matrix:
         os: [Ubuntu, MacOS, Windows]
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.8', '3.9', '3.10', '3.11']
         exclude: # TODO: remove this when pip is fixed
           - os: Windows
             python-version: '3.11'

.github/workflows/publish-docs.yml

@@ -0,0 +1,36 @@
+name: Publish documentation website
+
+on:
+  push:
+    branches:
+      - main
+      - doc/init-sphinx
+
+jobs:
+
+  publish-docs:
+    name: Publish docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+          cache: poetry
+
+      - name: Install dependencies
+        run: poetry install --without dev
+
+      - name: Build sphinx documentation website
+        run: poetry run poe docs
+
+      - name: Publish documentation website to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build
+          commit_message: ${{ github.event.head_commit.message }}

README.md

@@ -0,0 +1,80 @@
+# Poe the Poet
+
+<img alt="Poe the Poet" src="./docs/_static/poe_logo_x2000.png" height="200" width="200" align="left"/>
+
+[![PyPI version](https://img.shields.io/pypi/pyversions/poethepoet.svg)](https://pypi.org/project/poethepoet/)
+[![PyPI version](https://img.shields.io/pypi/v/poethepoet.svg)](https://pypi.org/project/poethepoet/)
+[![PyPI version](https://img.shields.io/pypi/dw/poethepoet.svg)](https://pypi.org/project/poethepoet/)
+[![PyPI version](https://img.shields.io/pypi/l/ansicolortags.svg)](https://github.com/nat-n/poethepoet/blob/doc/init-sphinx/LICENSE)
+
+**A batteries included task runner that works well with [poetry](https://python-poetry.org/).**
+
+[Read the docs](https://poethepoet.natn.io/)
+
+<br clear="both"/>
+
+## Features
+
+
+- ✅ Straight forward declaration of project tasks in your pyproject.toml
+
+- ✅ Tasks are run in poetry's virtualenv (or another env you specify)
+
+- ✅ Shell completion of task names (and global options too for zsh)
+
+- ✅ The poe CLI can be used standalone, or as a [plugin for the poetry](https://poethepoet.natn.io/poetry_plugin.html)
+
+- ✅ Tasks can be commands, shell scripts, python expressions, or references to python functions
+
+- ✅ Concise commands with extra arguments passed to the task `poe [options] task [task_args]`
+
+- ✅ Easily define CLI arguments for your tasks
+
+- ✅ Tasks can specify and reference environment variables, even without a shell
+
+- ✅ Tasks are self documenting, with optional help messages (just run `poe` with no arguments)
+
+- ✅ Tasks can be composed into sequences or DAGs
+
+- ✅ Works with `.env` files
+
+
+## Quick start
+
+1. Install the Poe the Poet via [pipx](https://pypa.github.io/pipx/) or [another method](https://poethepoet.natn.io/installation.html).
+
+  ```sh
+  pipx install poethepoet
+  ```
+
+2. Define some tasks in your **pyproject.toml**
+
+  ```toml
+  [tool.poe.tasks]
+  test         = "pytest --cov=my_app"                         # a simple command task
+  serve.script = "my_app.service:run(debug=True)"              # python script based task
+  tunnel.shell = "ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &"   # (posix) shell based task
+  ```
+
+3. Run your tasks via the CLI
+
+  ```sh
+  $ poe test -v tests/unit # extra CLI arguments are appended to the underlying command
+  Poe => pytest --cov=my_app
+  ...
+  ```
+
+If you're using poetry, then poe will automatically use CLI tools and libraries from your poetry managed virtualenv without you having to run `poetry run` or `poetry shell`
+
+Poe can also be [used without poetry](https://poethepoet.natn.io/index.html#usage-without-poetry).
+
+## Contributing
+
+There's plenty to do, come say hi in the [discussions](https://github.com/nat-n/poethepoet/discussions) or [open an issue](https://github.com/nat-n/poethepoet/issues)! 👋
+
+Also check out the [CONTRIBUTING.MD](https://github.com/nat-n/poethepoet/blob/main/.github/CONTRIBUTING.md) 🤓
+
+
+## License
+
+[MIT](https://github.com/nat-n/poethepoet/blob/main/LICENSE)