textmate-grammar-python 0.6.0__tar.gz → 0.7.0__tar.gz

textmate_grammar_python-0.7.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "monthly"

textmate_grammar_python-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: "CI"
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - '.github/workflows/ci.yml'
+      - '.pre-commit-config.yaml'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'src/**'
+      - 'test/**'
+
+jobs:
+
+  unit-test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "latest"
+
+      - name: Install the project dependencies
+        run: uv sync --no-dev --group test --python ${{ matrix.python-version }}
+
+      - name: Test with pytest
+        run: |
+          uv run pytest -v test/unit
+
+  differential-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        node-version: [20]
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Setup node ${{ matrix.node-version }}
+        uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install node dependencies
+        run: |
+          cd test/differential/node_root
+          npm ci
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "latest"
+
+      - name: Install the project dependencies
+        run: uv sync --no-dev --group test --python ${{ matrix.python-version }}
+
+      - name: Test with pytest
+        run: |
+          uv run pytest -v test/differential

textmate_grammar_python-0.7.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+      - 'docs/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --no-dev --group doc
+
+      - name: Sphinx build
+        run: uv run make -C docs html
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html
+          force_orphan: true

textmate_grammar_python-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: release with uv
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'src/textmate_grammar/__init__.py'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "latest"
+
+      - name: Install the project dependencies
+        run: uv sync --no-dev
+
+      - name: Build package distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish

textmate_grammar_python-0.7.0/.gitignore

@@ -0,0 +1,171 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/apidocs/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff cache
+.ruff_cache/
+
+# Textemate cache
+.textmate_cache/
+
+# Rye lock-files
+requirements.lock
+requirements-dev.lock

textmate_grammar_python-0.7.0/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "syntaxes"]
+	path = syntaxes/matlab
+	url = https://github.com/mathworks/MATLAB-Language-grammar
+[submodule "vscode-markdown-tm-grammar"]
+	path = syntaxes/markdown
+	url = https://github.com/microsoft/vscode-markdown-tm-grammar

textmate_grammar_python-0.7.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.17.2
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+        pass_filenames: false
+      # Run the formatter.
+      - id: ruff-format
+        pass_filenames: false
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.4.0
+    hooks:
+    - id: mypy
+      additional_dependencies: ["types-pyyaml"]
+      exclude: |
+        (?x)^(
+            example.py|
+            test\/.*.py|
+            docs\/.*.py
+        )$
+
+  - repo: local
+    hooks:
+    - id: uv-export
+      name: export doc requirements from uv.lock
+      entry: uv export --no-emit-project --no-dev --group doc --format requirements-txt -o docs/requirements.txt
+      language: system
+      pass_filenames: false
+      files: ^(pyproject\.toml|uv\.lock)$

textmate_grammar_python-0.7.0/.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": true
+        }
+    ]
+}

textmate_grammar_python-0.7.0/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "python.testing.pytestArgs": [
+        "test"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/.mypy_cache": true,
+        "**/.pytest_cache": true,
+        "**/.ruff_cache": true,
+        "**/.tox": true,
+    },
+}

textmate_grammar_python-0.7.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.7.0
+
+This is a breaking 0.x release and a full port of the vscode-textmate 9.3.2 tokenization engine. It includes the rule model, scope-selector matcher, state stacks, tokenization loop, plist/JSON grammar loading, and Registry.
+
+- The public API now follows vscode-textmate: `Registry`, `parseRawGrammar`, `Grammar.tokenizeLine`, `IToken`, and line-to-line `ruleStack` state.
+- **Breaking:** the legacy element-tree API was removed. `ContentElement`, `flatten`, `parse_file`, and `parse_string` are no longer available.
+- The minimum supported Python version is 3.10.
+- Differential CI compares the Python engine with the pinned Node oracle across a 50-case MATLAB, Markdown, Python, and TypeScript corpus.
+- Consolidates the dependency updates from the preceding implementation work (`onigurumacffi`, PyYAML, and `charset-normalizer`); test, development, and documentation tools are managed in uv dependency groups.

textmate_grammar_python-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+Use [uv](https://docs.astral.sh/uv/) to install the project and test dependencies. Install [pre-commit](https://pre-commit.com/) to run Ruff and mypy checks automatically:
+
+```bash
+uv sync --group test
+uv run pre-commit install
+```
+
+Run the unit tests with:
+
+```bash
+uv run pytest -q test/unit
+```
+
+The differential suite compares this port with the pinned Node oracle. It needs Node on `PATH`, the grammar corpus submodules, and the oracle's npm dependencies:
+
+```bash
+git submodule update --init
+(cd test/differential/node_root && npm ci)
+uv run pytest -q test/differential
+```
+
+Run the full checks with `uv run ruff check src/` and `uv run mypy .`. For the documentation build, install the doc group (`uv sync --no-dev --group doc`) and run `uv run make -C docs html`.

textmate_grammar_python-0.7.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: textmate-grammar-python
+Version: 0.7.0
+Summary: A Python port of the vscode-textmate grammar tokenization engine.
+Project-URL: Repository, https://github.com/watermarkhu/textmate-grammar-python
+Project-URL: Documentation, https://textmate-grammar-python.readthedocs.io
+Author-email: Mark Shui Hu <watermarkhu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: grammar,syntax-highlighting,textmate,tokenization,vscode
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.10
+Requires-Dist: charset-normalizer<4.0.0,>=3.3.2
+Requires-Dist: onigurumacffi<2.0.0,>=1.3.0
+Requires-Dist: pyyaml<7.0.0,>=6.0.1
+Description-Content-Type: text/markdown
+
+[![PyPI - Version](https://img.shields.io/pypi/v/textmate-grammar-python.svg)](https://pypi.python.org/pypi/textmate-grammar-python)
+[![PyPI - License](https://img.shields.io/pypi/l/textmate-grammar-python.svg)](https://github.com/watermarkhu/textmate-grammar-python/tree/main?tab=MIT-1-ov-file)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Python versions](https://img.shields.io/pypi/pyversions/textmate-grammar-python.svg)](https://pypi.python.org/pypi/textmate-grammar-python)
+[![CI/CD](https://github.com/watermarkhu/textmate-grammar-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/watermarkhu/textmate-grammar-python/blob/main/.github/workflows/ci.yml)
+[![readthedocs](https://readthedocs.org/projects/textmate-grammar-python/badge/?version=latest)](https://textmate-grammar-python.readthedocs.io)
+
+# textmate-grammar-python
+
+A Python port of the [vscode-textmate](https://github.com/microsoft/vscode-textmate) grammar tokenization engine. It loads TextMate grammars and tokenizes source one line at a time, carrying the rule stack between lines.
+
+The `textmate_grammar.engine` modules port the rule model, scope matcher, grammar loading and registry, and stateful tokenization loop. A differential suite compares token boundaries and scope paths against the real vscode-textmate 9.3.2 Node oracle across a 50-case MATLAB, Markdown, Python, and TypeScript corpus.
+
+## Usage
+Requires Python 3.10 or newer. Install with:
+```bash
+pip install textmate-grammar-python
+```
+
+The public API follows vscode-textmate's registry and line-tokenization model. A registry loads raw grammar data by scope name; pass each line's returned `ruleStack` into the next call:
+
+```python
+from pathlib import Path
+
+from textmate_grammar import INITIAL, Registry, parseRawGrammar
+
+grammar_path = Path("MATLAB.tmLanguage")
+raw_grammar = parseRawGrammar(grammar_path.read_text(), str(grammar_path))
+registry = Registry({"loadGrammar": lambda scope: raw_grammar if scope == "source.matlab" else None})
+grammar = registry.loadGrammar("source.matlab")
+state = INITIAL
+for line in Path("example.m").read_text().splitlines():
+    result = grammar.tokenizeLine(line, state)
+    state = result.ruleStack
+    print(result.tokens)  # each token has startIndex, endIndex, and scopes
+```
+
+The bundled MATLAB and Markdown grammar helpers are also available from `textmate_grammar.parsers.matlab` and `textmate_grammar.parsers.markdown`.
+
+## Migrating from 0.6.x
+
+This 0.7.0 release is breaking within the 0.x series. The old `LanguageParser` / `ContentElement` tree API (including `parse_file`, `parse_string`, and `flatten`) is removed without compatibility shims. Replace it with `Registry`, `parseRawGrammar`, `Grammar.tokenizeLine`, `IToken` tokens, and the `ruleStack` state API shown above.
+
+## Information
+
+- For further information, please checkout the [documentation](https://textmate-grammar-python.readthedocs.io/en/latest/). 
+- To setup an environment for development, see [CONTRIBUTING.md](https://github.com/watermarkhu/textmate-grammar-python/blob/main/CONTRIBUTING.md)

textmate_grammar_python-0.7.0/README.md

@@ -0,0 +1,49 @@
+[![PyPI - Version](https://img.shields.io/pypi/v/textmate-grammar-python.svg)](https://pypi.python.org/pypi/textmate-grammar-python)
+[![PyPI - License](https://img.shields.io/pypi/l/textmate-grammar-python.svg)](https://github.com/watermarkhu/textmate-grammar-python/tree/main?tab=MIT-1-ov-file)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Python versions](https://img.shields.io/pypi/pyversions/textmate-grammar-python.svg)](https://pypi.python.org/pypi/textmate-grammar-python)
+[![CI/CD](https://github.com/watermarkhu/textmate-grammar-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/watermarkhu/textmate-grammar-python/blob/main/.github/workflows/ci.yml)
+[![readthedocs](https://readthedocs.org/projects/textmate-grammar-python/badge/?version=latest)](https://textmate-grammar-python.readthedocs.io)
+
+# textmate-grammar-python
+
+A Python port of the [vscode-textmate](https://github.com/microsoft/vscode-textmate) grammar tokenization engine. It loads TextMate grammars and tokenizes source one line at a time, carrying the rule stack between lines.
+
+The `textmate_grammar.engine` modules port the rule model, scope matcher, grammar loading and registry, and stateful tokenization loop. A differential suite compares token boundaries and scope paths against the real vscode-textmate 9.3.2 Node oracle across a 50-case MATLAB, Markdown, Python, and TypeScript corpus.
+
+## Usage
+Requires Python 3.10 or newer. Install with:
+```bash
+pip install textmate-grammar-python
+```
+
+The public API follows vscode-textmate's registry and line-tokenization model. A registry loads raw grammar data by scope name; pass each line's returned `ruleStack` into the next call:
+
+```python
+from pathlib import Path
+
+from textmate_grammar import INITIAL, Registry, parseRawGrammar
+
+grammar_path = Path("MATLAB.tmLanguage")
+raw_grammar = parseRawGrammar(grammar_path.read_text(), str(grammar_path))
+registry = Registry({"loadGrammar": lambda scope: raw_grammar if scope == "source.matlab" else None})
+grammar = registry.loadGrammar("source.matlab")
+state = INITIAL
+for line in Path("example.m").read_text().splitlines():
+    result = grammar.tokenizeLine(line, state)
+    state = result.ruleStack
+    print(result.tokens)  # each token has startIndex, endIndex, and scopes
+```
+
+The bundled MATLAB and Markdown grammar helpers are also available from `textmate_grammar.parsers.matlab` and `textmate_grammar.parsers.markdown`.
+
+## Migrating from 0.6.x
+
+This 0.7.0 release is breaking within the 0.x series. The old `LanguageParser` / `ContentElement` tree API (including `parse_file`, `parse_string`, and `flatten`) is removed without compatibility shims. Replace it with `Registry`, `parseRawGrammar`, `Grammar.tokenizeLine`, `IToken` tokens, and the `ruleStack` state API shown above.
+
+## Information
+
+- For further information, please checkout the [documentation](https://textmate-grammar-python.readthedocs.io/en/latest/). 
+- To setup an environment for development, see [CONTRIBUTING.md](https://github.com/watermarkhu/textmate-grammar-python/blob/main/CONTRIBUTING.md)

textmate_grammar_python-0.7.0/docs/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    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# 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) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

textmate_grammar_python-0.7.0/docs/conf.py

@@ -0,0 +1,54 @@
+from datetime import date
+
+# -- Project information -----------------------------------------------------
+
+project = "TextMate Grammar Python"
+version = "0.7.0"
+copyright = f"{date.today().year}, Mark Shui Hu"
+author = "Mark Shui Hu"
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "myst_parser",
+    "autodoc2",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+    "sphinxcontrib.mermaid",
+]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
+myst_enable_extensions = ["fieldlist", "deflist"]
+
+# -- HTML output -------------------------------------------------
+
+html_theme = "furo"
+html_title = "TextMate Grammar Python"
+html_theme_options = {
+    "top_of_page_button": "edit",
+    "source_repository": "https://github.com/watermarkhu/textmate-grammar-python/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/watermarkhu/textmate-grammar-python",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+}
+
+# --- Autodoc configuration ------
+
+autodoc2_packages = ["../src/textmate_grammar"]
+autodoc2_hidden_objects = ["dunder", "private", "inherited"]

textmate_grammar_python-0.7.0/docs/index.md

@@ -0,0 +1,37 @@
+# Textmate Grammar Python
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![CI/CD](https://github.com/watermarkhu/textmate-grammar-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/watermarkhu/textmate-grammar-python/blob/main/.github/workflows/ci.yml)
+[![readthedocs](https://readthedocs.org/projects/textmate-grammar-python/badge/?version=latest)](https://textmate-grammar-python.readthedocs.io)
+
+A Python port of the [vscode-textmate](https://github.com/microsoft/vscode-textmate) grammar tokenization engine. It parses TextMate grammars and tokenizes source line by line while preserving the state stack between lines.
+
+The engine's token streams are checked against vscode-textmate 9.3.2 using a Node oracle and a differential corpus spanning MATLAB, Markdown, Python, and TypeScript.
+
+```{mermaid}
+flowchart LR
+    G[TextMate grammar] --> R[Registry]
+    C[source lines] --> R
+    R --> T[tokens + rule stack]
+    T -. differential comparison .-> O[vscode-textmate 9.3.2 oracle]
+    click O "https://github.com/microsoft/vscode-textmate"
+```
+
+## Index 
+
+```{toctree}
+:maxdepth: 2
+
+started
+languages
+tokenization
+apidocs/index
+```
+
+## Sources
+- [Textmate guide](https://www.apeth.com/nonblog/stories/textmatebundle.html)
+- [VSCode Syntax Highlighting guide](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide)
+- [vscode-textmate](https://github.com/microsoft/vscode-textmate)
+- [Macromates texmate](https://macromates.com/textmate/manual/)