feat: make Sphinx plugin, CLI tooling, and action for GH

.github/ISSUE_TEMPLATE/bug.md

@@ -1,23 +1,13 @@
 ---
 name: Bug report
 about: Report an error that you've encountered.
-labels: bug
+labels: 'category: bug'
 ---
 
 ### Environment information
 
-- `ape` and plugin versions:
-
-```
-$ ape --version
-# ...copy and paste result of above command here...
-
-$ ape plugins list
-# ...copy and paste result of above command here...
-```
-
+- OS: macOS / linux / win
 - Python Version: x.x.x
-- OS: osx/linux/win
 
 ### What went wrong?
 

.github/ISSUE_TEMPLATE/feature.md

@@ -1,7 +1,7 @@
 ---
 name: Feature request
 about: Request a new feature, or an improvement to existing functionality.
-labels: enhancement
+labels: 'category: feature'
 ---
 
 ### Overview

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,16 +1,23 @@
 ### What I did
 
+<!-- Create a summary of the changes -->
+
 <!-- The `fixes:` field denotes an issue that will be marked resolved by merging this PR -->
 
 fixes: #
 
 ### How I did it
 
+<!-- Discuss the thought process behind the change -->
+
 ### How to verify it
 
+<!-- Discuss any methods that should be used to verify the change -->
+
 ### Checklist
 
-- [ ] Passes all linting checks (pre-commit and CI jobs)
-- [ ] New test cases have been added and are passing
+<!-- All PRs must complete the following checklist before being merged -->
+
+- [ ] All changes are completed
+- [ ] New test cases have been added
 - [ ] Documentation has been updated
-- [ ] PR title follows [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) standard (will be automatically included in the changelog)

.github/release-drafter.yml

@@ -13,6 +13,8 @@ categories:
       - 'refactor'
       - 'chore'
       - 'docs'
+      - 'perf'
+      - 'test'
 
 change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
 change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
@@ -31,7 +33,7 @@ version-resolver:
 
 template: |
   ## Changes
-  
+
   $CHANGES
-  
+
   Special thanks to: $CONTRIBUTORS

.github/workflows/codeql.yaml → .github/workflows/codeql.yml

@@ -23,12 +23,12 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: python
 
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3

.github/workflows/prtitle.yaml

@@ -8,7 +8,7 @@ on:
       - synchronize
 
 jobs:
-    check:
+    pr-title:
         runs-on: ubuntu-latest
 
         steps:
@@ -20,7 +20,9 @@ jobs:
               python-version: "3.10"
 
         - name: Install Dependencies
-          run: pip install commitizen
+          run: |
+            python -m pip install --upgrade pip
+            pip install -r cz-requirement.txt
 
         - name: Check PR Title
           env:

.github/workflows/stale-prs.yml

@@ -0,0 +1,20 @@
+name: "Close stale PRs"
+on:
+  schedule:
+    - cron: '30 1 * * *'
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-pr-message: 'This pull request is considered stale because it has been open 30 days with no activity. Remove stale label, add a comment, or make a new commit, otherwise this PR will be closed in 5 days.'
+          close-pr-message: 'This PR was closed because it has been inactive for 35 days.'
+          stale-pr-label: "stale"
+          close-pr-label: "inactive"
+          days-before-pr-stale: 30
+          days-before-pr-close: 5
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yaml

@@ -56,24 +56,3 @@ jobs:
 
         - name: Run MyPy
           run: mypy .
-
-# NOTE: uncomment this block after you've marked tests with @pytest.mark.fuzzing
-#    fuzzing:
-#        runs-on: ubuntu-latest
-#
-#        strategy:
-#            fail-fast: true
-#
-#        steps:
-#        - uses: actions/checkout@v4
-#
-#        - name: Setup Python
-#          uses: actions/setup-python@v5
-#          with:
-#              python-version: "3.10"
-#
-#        - name: Install Dependencies
-#          run: pip install .[test]
-#
-#        - name: Run Tests
-#          run: pytest -m "fuzzing" --no-cov -s

CONTRIBUTING.md

@@ -4,14 +4,14 @@ To get started with working on the codebase, use the following steps prepare you
 
 ```bash
 # clone the github repo and navigate into the folder
-git clone https://github.com/ApeWorX/docs-build.git
-cd docs-build
+git clone https://github.com/ApeWorX/sphinx-ape.git
+cd sphinx-ape
 
 # create and load a virtual environment
 python3 -m venv venv
 source venv/bin/activate
 
-# install <PROJECT_NAME> into the virtual environment
+# install sphinx-ape into the virtual environment
 python setup.py install
 
 # install the developer dependencies (-e is interactive mode)

README.md

@@ -1,61 +1,80 @@
 # Quick Start
 
-A script that uses sphinx to develop documentation for ApeWorX plugins.
+`sphinx-ape` is a documenation plugin for the Sphinx framework.
+The purpose of this plugin to share code for generating documentation across all ApeWorX repositories.
 
 ## Dependencies
 
 - [python3](https://www.python.org/downloads) version 3.9 up to 3.12.
 
 ## Quick Usage
 
-To use this to build the documentation in an Ape plugin, add this to your documentation workflow (e.g. your `.github/workflows/docs.yaml` file).
+To use this sphinx plugin, create a `docs/` folder in your Python package.
+Inside this folder, create a `conf.py` with the following content:
 
-```bash
-- name: Clone ApeDocumentationBuilder
-  run: git clone https://github.com/ApeWorX/ApeDocumentationBuilder.git
+```txt
+extensions = ["sphinx_ape"]
+```
 
-- name: Set up environment variable
-  run: echo "GITHUB_REPO=$(echo ${GITHUB_REPOSITORY} | cut -d'/' -f2)" >> $GITHUB_ENV
+Then, create an `index.rst` file with the following content:
 
-- name: Build HTML artifact
-  run: |
-    cd ApeDocumentationBuilder
-    python build_docs.py
+```txt
+.. dynamic-toc-tree::
 ```
 
-### Running the docs locally
+You don't have to configure anything else; it will just work.
 
-First, clone the repo into your root project directory.
+Now, you can begin writing your documentation.
+There are three directories you can create:
 
-```bash
-git clone https://github.com/ApeWorX/ApeDocumentationBuilder.git
-```
+1. `userguides/` - a directory containing how-to guides for how to use your package.
+2. `commands/` - `.rst` files for the `sphinx-click` plugin for CLI-based references.
+3. `methoddocs/` - Autodoc `.rst` files controlling your generated method documentation.
+
+Once you have developed your documentation, ensure you have `sphinx-ape` installed.
+For example, clone this repo and install it using `pip install <path/to/sphinx-ape>` or install from `pypi` by doing `pip intall sphinx-ape`.
 
-Then, set up the `GITHUB_REPO` environment variable:
+After `sphinx-ape` is installed, build your projects' documentation by doing:
 
-```bash
-export GITHUB_REPO=<project-name>
+```sh
+sphinx-ape build <path/to/project>
 ```
 
-Next, run the following in the `ApeDocumentationBuilder` directory:
+Most commonly, you will already be in your project's directory, so you will do:
 
-```bash
-cd ApeDocumentationBuilder
-python build_docs.py
+```sh
+sphinx-ape build .
 ```
 
-For the best viewing experience, use a local server:
+Then, to view the documentation, run the `serve` command:
 
-```bash
-python -m http.server --directory "../docs/_build/" --bind 127.0.0.1 1337
+```sh
+sphinx-ape serve <path/to/project>
+# When in directory already
+sphinx-ape serve .
 ```
 
-Then, open your browser to `127.0.0.1:1337` and click the `ape` directory link.
+To automatically open a browser at the same time as serving, use the `--open` flag:
 
-```{note}
-Serving from `"docs/_build/"` rather than `"docs/_build/<project>"` is necessary to make routing work.
+```sh
+sphinx-ape serve . --open
 ```
 
+## GitHub Action
+
+This GitHub action is meant for building the documentation in both core Ape as well any Ape plugin.
+The aciton may also work for regular Python packages with a documentation-strategy similar to Ape.
+
+There are three GitHub events that trigger this action:
+
+1. Push to 'main': we build into 'latest/'.
+   The GitHub action will commit these changes to the 'gh-pages' branch.
+
+2. Release: we copy 'latest/' into the release dir, as well as to 'stable/'.
+   The GitHub action will commit these changes to the 'gh-pages' branch.
+
+3. Pull requests or local development: We ensure a successful build.
+
 ## Development
 
 Please see the [contributing guide](CONTRIBUTING.md) to learn more how to contribute to this project.