Merge pull request #27 from Quansight-Labs/trallard/hatch

ENH - Move to hatch for dev/build

.github/workflows/preview-pr.yml

@@ -0,0 +1,88 @@
+name: Deploy PR previews on GH pages
+
+on:
+    push:
+        branches:
+            - main
+    pull_request:
+        branches:
+            - main
+
+concurrency: preview-${{ github.ref }}
+env:
+    FORCE_COLOR: "1"
+    PYTHONIOENCODING: utf-8
+    SETUPTOOLS_SCM_PRETEND_VERSION: "1.0" # avoid warnings about shallow checkout
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository 🛎
+      uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+
+    - name: Install dependencies 📦
+      run: |
+        pip install pygments>=1.5
+        pip install -e .[dev]
+
+    - name: Build the demo pages 📚
+      run: |
+        python test/run_css.py --save-dir docs
+
+    - name: Deploy PR Preview
+      uses: rossjrw/pr-preview-action@v1.2.0
+      with:
+        source-dir: docs
+        preview-branch: gh-pages
+
+  publish-pages:
+    runs-on: ubuntu-latest
+    needs: deploy-preview
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - name: Checkout repository 🛎
+      uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+
+    - name: Install dependencies 📦
+      run: |
+        pip install pygments>=1.5
+        pip install -e .[dev]
+
+    - name: Build the demo pages 📚
+      run: |
+        python test/run_css.py --save-dir docs
+
+    - name: Setup Pages 🛠
+      uses: actions/configure-pages@v3
+
+    - name: Upload artifact 📥
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: "docs"
+    - name: Deploy to GitHub Pages 🚀
+      id: deployment
+      uses: actions/deploy-pages@v2

.github/workflows/pypi-package.yml

@@ -0,0 +1,77 @@
+name: Build and maybe upload PyPI package
+
+on:
+    push:
+        branches:
+            - main
+        tags:
+            - "*"
+    pull_request:
+        branches:
+            - main
+    release:
+        types:
+        - published
+    workflow_dispatch:
+
+env:
+    FORCE_COLOR: "1" # Make tools pretty.
+
+permissions:
+    contents: read
+    id-token: write
+
+jobs:
+    # Always build and lint
+    build-package:
+        name: Build package 📦
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout repository 🛎
+              uses: actions/checkout@v3
+              with:
+                fetch-depth: 0
+
+            - uses: hynek/build-and-inspect-python-package@v1
+
+    # Upload to Test PyPI on every commit on main.
+    release-test-pypi:
+        name: Publish in-dev package to test.pypi.org
+        environment: release-test-pypi
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        runs-on: ubuntu-latest
+        needs: build-package
+
+        steps:
+            - name: Download package built in previous job 📥
+              uses: actions/download-artifact@v3
+              with:
+                name: Packages
+                path: dist
+            - name: Upload package to Test PyPI 🚀
+              uses: pypa/gh-action-pypi-publish@release/v1
+              with:
+                password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+                repository-url: https://test.pypi.org/legacy/
+
+    # Upload to real PyPI on GitHub Releases.
+    release-pypi:
+        name: Publish released package to pypi.org 🚀
+        environment: release-pypi
+        if: github.event.action == 'published'
+        runs-on: ubuntu-latest
+        needs: build-package
+
+        steps:
+            - name: Download packages built by build-and-inspect-python-package 📥
+              uses: actions/download-artifact@v3
+              with:
+                name: Packages
+                path: dist
+
+            - name: Upload package to PyPI 🚀
+              uses: pypa/gh-action-pypi-publish@release/v1
+              with:
+                password: ${{ secrets.PYPI_API_TOKEN }}
+                print-hash: true

.gitignore

@@ -50,6 +50,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache
 
 # Translations
 *.mo

.pre-commit-config.yaml

@@ -21,6 +21,8 @@ repos:
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
+      - id: check-toml
+      - id: check-yaml
 
   # python
   - repo: https://github.com/psf/black
@@ -33,7 +35,6 @@ repos:
     rev: v0.0.254
     hooks:
       - id: ruff
-        args: ["--fix", "--exclude", "test/scripts/*.py"]
 
   - repo: https://github.com/pycqa/isort
     rev: 5.12.0
@@ -42,7 +43,6 @@ repos:
         name: isort
         additional_dependencies: [toml]
         files: \.py$
-        args: ["--profile", "black"]
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.7.1

CONTRIBUTING.md

@@ -4,10 +4,11 @@ Welcome! And thanks for taking your time to contribute to this project 🤩
 
 - [Contributing to accessible pygments themes](#contributing-to-accessible-pygments-themes)
   - [Submit an issue 📬](#submit-an-issue-)
-  - [Creating your development environment 👩🏻‍💻 👨🏼‍💻](#creating-your-development-environment--)
-    - [Fork this repository ⏬](#fork-this-repository-)
-    - [Install dependencies 💽](#install-dependencies-)
-    - [Run the tests 🏃🏻‍♀️ 🏃‍♂️](#run-the-tests-️-️)
+  - [Contributing to this package](#contributing-to-this-package)
+    - [Pre-requisites 📦](#pre-requisites-)
+    - [Creating your development environment 👩🏻‍💻 👨🏼‍💻](#creating-your-development-environment--)
+    - [Running the tests](#running-the-tests)
+    - [Rendering the HTML examples](#rendering-the-html-examples)
   - [Adding a new theme 🎨](#adding-a-new-theme-)
     - [Where to add a new theme 👩🏼‍🎨](#where-to-add-a-new-theme-)
     - [Customize your `style.py` file](#customize-your-stylepy-file)
@@ -21,47 +22,79 @@ Welcome! And thanks for taking your time to contribute to this project 🤩
 
 Please share your thoughts for fixes and features in the issue tracker.
 When doing so, please a clear description and provide useful environment information.
+Please share your thoughts for fixes and features [in the issue tracker](https://github.com/Quansight-Labs/accessible-pygments/issues).
+When doing so, add a clear description, and please provide as much information as possible about your environment.
 
-## Creating your development environment 👩🏻‍💻 👨🏼‍💻
+## Contributing to this package
 
-For creating your development environment locally you will need to have the following tools installed:
+### Pre-requisites 📦
 
-- 🐍 An environment manager like `conda` or `pyenv`
-- 📝 `git`
+You will need to have the following installed locally:
+
+- `git`
 - Python >= 3.9
+- [hatch](https://hatch.pypa.io/)
 
-### Fork this repository ⏬
+### Creating your development environment 👩🏻‍💻 👨🏼‍💻
 
-Fork this repository to your profile and clone it to your local machine:
+1. Fork this repository to your GitHub account, then clone it to your local machine:
 
-```bash
-git clone <LINK-TO-YOUR-FORK>
-```
+   ```bash
+    git clone https://github.com/<your-username>/accessible-pygments.git
+   ```
+
+   Remember that this fork is a copy of the repository and any changes in it doesn't affect the original one.
 
-Remember that this fork is a copy of the repository and any change done in it doesn't affect the original one.
+2. From here you can create your local environments with hatch:
 
-### Install dependencies 💽
+   ```bash
+    hatch env create
+   ```
 
-Once you have the local clone in your machine, you need to install the dependencies.
-You can create a new environment for this project and install the dependencies there:
+3. You can verify that the environment was created successfully by running:
+
+   ```console
+    $ hatch env show
+   ┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
+   ┃ Name    ┃ Type    ┃ Dependencies ┃ Scripts     ┃
+   ┡━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
+   │ default │ virtual │              │             │
+   ├─────────┼─────────┼──────────────┼─────────────┤
+   │ dev     │ virtual │              │ css         │
+   │         │         │              │ render_html │
+   ├─────────┼─────────┼──────────────┼─────────────┤
+   │ test    │ virtual │ hypothesis   │ tests       │
+   │         │         │ pytest       │             │
+   └─────────┴─────────┴──────────────┴─────────────┘
+   ```
+
+Alternatively you can use conda to create your environment:
 
 ```bash
 conda create -n a11y-pygments-dev python=3.9
 conda activate a11y-pygments-dev
 pip install -e .
 ```
 
-After running these instructions you will have an environment named `a11y-pygments-dev`, with the requirements installed and this package installed in development version.
+After running these instructions you will have an environment named `a11y-pygments-dev`, with a development version of the package installed.
+
+### Running the tests
+
+You can run the tests directly with hatch:
 
-### Run the tests 🏃🏻‍♀️ 🏃‍♂️
+```bash
+hatch run test:tests
+```
 
-Once the development environment is ready run the following command:
+### Rendering the HTML examples
+
+You can generate individual HTML files for each of the themes included in `accessible_pygments` by running:
 
 ```bash
-python test/run_tests.py
+hatch run dev:render_html
 ```
 
-You will see the results under `test/results` in HTML format for each supported theme.
+This will add the HTML files under `test/results` for each supported theme.
 We recommend using your favorite browser to see the rich HTML output.
 
 ## Adding a new theme 🎨
@@ -89,23 +122,18 @@ To add a new theme, please create a folder with your new theme name, like `white
 You can use as a base one of our existing themes, this file needs to define a new class named `Theme` with the new colors and rules you want.
 
 > **NOTE** 📝
-> Please try to encapsulate all the raw colors in the `Colors` `enum` and call them in the rules section. This will help us with maintenance 🙏.
+> Please try to encapsulate all the raw colors in the `Colors` `enum` and call them in the rules section.
+> This will help us with maintenance 🙏.
 
 ### Visualize and debug your theme
 
-To see and debug your theme re-install the package via:
-
-```bash
-pip install -e .
-```
-
-Then generate the HTML results:
+While working on your theme, it might be helpful to generate the individual HTML files with the following command:
 
 ```bash
-python test/run_tests.py
+hatch dev:render_html
 ```
 
-If successful, you should be able to see the results of your new theme under `test/results/<your-theme>` in HTML format.
+If successful, you should be able to see the results of your new theme under `test/results/<your-theme>`.
 
 ### Update the `README.md` file
 
@@ -122,17 +150,18 @@ Also, don't forget to add the name of your theme to our list of supported themes
 You can generate the CSS file automatically through:
 
 ```bash
-python a11y_pygments/test/run_css.py
+hatch dev:create_css
 ```
 
-The file should appear in the folder of your new theme.
+This will add the CSS file under `a11y_pygments/<your-theme>/style.css` and in the `docs` directory.
 
 #### Add your theme to our static page
 
 We have a demo page where you will be able to change the style of different languages at the same time.
-To add your new theme please go to the file `test/index.html`. Under themes, we have a link to all the generated CSS files.
+To add your new theme:
 
-You will have to manually add a new link to your new theme:
+1. Open the `[docs/index.html](docs/index.html)` file.
+2. Add a new link to your new theme in the `themes` section:
 
 ```HTML
 ...
@@ -143,8 +172,8 @@ You will have to manually add a new link to your new theme:
 
 ```
 
-With this change you will be able to open `test/index.html` in your favorite browser and find your new theme in our demo!
+With this change you will be able to open `docs/index.html` in your favorite browser and find your new theme in our demo!
 
 ### Create a Pull Request
 
-Once you have the folder with the described files, please open a Pull Request 👏🏻
+Once you have added and verified your theme you should be ready to open a Pull Request 👏🏻