Finish Implementation (#1)

* impl + tests

* Fix dirhtml redirects to index.html

* run black

* Simplify error messages

* Simplify dirhtml handling

* add jinja support

* Update instructions

* Add details to readme

* add function descriptions

* add ci

* ci fix os names

* ci fix

* Remove Pypy3 testing

* Fix Formatting

* Add testing section to readme

* readme: Add supported builders

* Fix and Add test for bad jinja template path

* run black

* Add missing method

* run black

* Add default values to stub func args

* builder: Add hint for renamed files

* Update setup.py

Co-authored-by: Dalton Smith <[email protected]>

* readme: mention rediraffe_branch can be a commit

Co-authored-by: Dalton Smith <[email protected]>

Author: TheTripleV

.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: ci
+on: [push, pull_request]
+
+jobs:
+  check-format:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Install Black
+      run: |
+        pip install black
+    - name: Run Black
+      run: |
+        black --check --diff .
+
+  test:
+    name: "Build (${{ matrix.os }} Python ${{ matrix.python-version }})"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.6', '3.7', '3.8']
+    steps:
+      - uses: actions/checkout@v2
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dev dependencies
+        shell: bash
+        run: |
+          set -xe
+          python -VV
+          python -m site
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -r dev-requirements.txt
+      - name: Build wheel
+        run: |
+          python setup.py bdist_wheel
+      - name: Install wheel
+        shell: bash
+        run: |
+          python -m pip install dist/*.whl
+      - name: Install test dependencies
+        run: |
+          python -m pip install -r test-requirements.txt
+      - name: Run Tests
+        run: |
+          cd tests
+          python -m pytest -vv --headless
+
+  pypi-release:
+    if: startsWith(github.ref, 'refs/tags/v') && github.repository_owner	== 'wpilibsuite'
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.7'
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -r dev-requirements.txt
+      - name: Build PyPI Wheel
+        run: |
+          python setup.py sdist
+          python setup.py bdist_wheel
+      - name: Publish a Python distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}

README.md

@@ -3,9 +3,19 @@
 
 Sphinx Extension to redirect files
 
+![Rediraffe](assets/rediraffe_logo.svg)
+
+This sphinx extension redirects non-existent pages to working pages.
+Additionally, a builder is provided to check that deleted/renamed files in your git repo are redirected. 
+
+Rediraffe supports the html and dirhtml builders.
+
+Note: Chained redirects will be resolved. For example, if a config has 6 chained redirects, all 6 links will redirect directly to the final link. The enduser will never experience more than 1 redirection.
+
 ## Installation
 
-`python -m pip install https://github.com/TheTripleV/sphinxext-rediraffe`
+`python -m pip install git+https://github.com/wpilibsuite/sphinxext-rediraffe.git`
+
 
 ## Usage
 Add `sphinxext.rediraffe` to your extensions list in your `conf.py`
@@ -15,17 +25,94 @@ extensions = [
    sphinxext.rediraffe,
 ]
 ```
-<!-- ## Options
+
+To check that deleted/renamed files in your git repo are in your redirects,
+1. Make sure `rediraffe_branch` and `rediraffe_redirects` are set in conf.py.
+2. Run the `rediraffecheckdiff` builder.
+
+## Options
 These values are placed in the conf.py of your sphinx project.
 
-* `linkcheckdiff_branch`
-    * Required. The branch to diff against.
+* `rediraffe_branch`
+    * Required for rediraffecheckdiff builder. The branch or commit to diff against.
+
+* `rediraffe_redirects`
+    * Required. A filename or dict containing redirects
 
-Note: linkcheckdiff is an extension of the linkcheck builder that ships with Sphinx. linkcheckdiff respects all of linkcheck's configuration options.
+* `rediraffe_template`
+    * Optional. A jinja template to use to render the inserted redirecting files. If not specified, a default template will be used. This template will only be accessed after the html/htmldir builder is finished; Therefore, this file may be generated as part of your build.
+    * variables available to rediraffe_template:
+        * `from_file` - the file being redirected as written in rediraffe_redirects.
+        * `to_file` - the destination file that from_file is redirected to as written in rediraffe_redirects.
+        * `from_url` - the path to from_url's html file (built by rediraffe) relative to the outdir.
+        * `to_url` - the path to to_url's built html file relative to the outdir.
+        * `rel_url` - the relative path from from_url to to_url.
 
 
 ## Example Config
 
+### redirects only (file)
+
+conf.py:
+```python
+rediraffe_redirects = "redirects.txt"
+```
+
+redirects.txt:
+```
+another.rst index.rst
+another2.rst another.rst
+```
+
+### redirects only (dict)
+
+conf.py:
 ```python
-linkcheckdiff_branch = "master"
-``` -->
+rediraffe_redirects = {
+    "another.rst": "index.rst",
+    "another2.rst": "another.rst",
+}
+```
+
+### redirects + diff checker
+
+conf.py:
+```python
+rediraffe_redirects = "redirects.txt"
+rediraffe_branch = "master~1"
+```
+
+### redirects with jinja template
+
+conf.py:
+```python
+rediraffe_redirects = "redirects.txt"
+rediraffe_template = "template.html"
+```
+
+template.html:
+```html
+<html>
+    <body>
+        <p>Your destination is {{to_url}}</p>
+    </body>
+</html>
+```
+
+A complex example can be found at tests/roots/ext/.
+
+## Testing
+
+Rediraffe uses pytest for testing.
+To run tests:
+1. Install this package
+2. Install test dependencies
+    ```bash
+    python -m pip install -r test-requirements.txt
+    ```
+3. Navigate to the tests directory and run
+    ```bash
+    python -m pytest --headless
+    ```
+
+The `--headless` flag ensures that a browser window does not open during browser backed selenium testing.