{"id":50770134,"url":"https://github.com/procitec/sphinx-gherkin-feature","last_synced_at":"2026-06-11T17:31:58.005Z","repository":{"id":358041310,"uuid":"1239685897","full_name":"procitec/sphinx-gherkin-feature","owner":"procitec","description":"Sphinx Extension to include Gherkin Feature as codeblocks with possible export to file","archived":false,"fork":false,"pushed_at":"2026-05-15T15:35:14.000Z","size":118,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T22:26:14.886Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/procitec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T10:38:22.000Z","updated_at":"2026-05-15T15:35:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/procitec/sphinx-gherkin-feature","commit_stats":null,"previous_names":["procitec/sphinx-gherkin-feature"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/procitec/sphinx-gherkin-feature","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/procitec%2Fsphinx-gherkin-feature","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/procitec%2Fsphinx-gherkin-feature/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/procitec%2Fsphinx-gherkin-feature/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/procitec%2Fsphinx-gherkin-feature/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/procitec","download_url":"https://codeload.github.com/procitec/sphinx-gherkin-feature/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/procitec%2Fsphinx-gherkin-feature/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34211061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-11T17:31:57.923Z","updated_at":"2026-06-11T17:31:57.986Z","avatar_url":"https://github.com/procitec.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sphinx-gherkin-feature\n\n`sphinx-gherkin-feature` is a Sphinx extension for documenting complete Gherkin feature scripts and optionally writing those scripts as `.feature` files during the Sphinx build.\n\nIt provides the domain directive:\n\n```rst\n.. gherkin:feature::\n   :filename: login\n\n   Feature: Login\n\n     Scenario: Successful login\n       Given a user account exists\n       When the user logs in\n       Then the dashboard is shown\n```\n\nThe directive body is rendered as a highlighted literal block. When file writing is enabled, the same body is also written as `login.feature`.\n\n## Installation\n\nThis project is configured for [`uv`](https://docs.astral.sh/uv/).\n\nFor local development:\n\n```bash\nuv sync --group dev --group docs\n```\n\nThe project pins `gherkin-lint` to the upstream GitHub release tag `v26.1.1` via `tool.uv.sources`:\n\n```toml\n[tool.uv.sources]\ngherkin-lint = { git = \"https://github.com/procitec/gherkin-lint.git\", tag = \"v26.1.1\" }\n```\n\nFor use in another uv-managed Sphinx project, add this package and the same source override for `gherkin-lint` in that project's `pyproject.toml`.\n\n## Configuration\n\nAdd the extension to `conf.py`:\n\n```python\nextensions = [\"sphinx_gherkin_feature\"]\n```\n\nAvailable configuration values:\n\n```python\n# Validate :filename: values. The .feature suffix is not part of the option.\ngherkin_feature_filename_regex = r\"^[a-z0-9_]+$\"\n\n# Write feature files after successful builds.\ngherkin_feature_write_file = False\n\n# Where generated files are written.\n# Relative paths are resolved below the Sphinx builder output directory.\n# Absolute paths are used as configured.\ngherkin_feature_output_dir = \"gherkin\"\n\n# Lint integration with procitec/gherkin-lint v26.1.0.\ngherkin_feature_lint = False\ngherkin_feature_lint_indent_size = 4\n\n# Optional Pygments highlighting integration.\ngherkin_feature_highlight = True\ngherkin_feature_pygments_language = \"gherkin-feature\"\ngherkin_feature_register_lexer = True\ngherkin_feature_lexer_aliases = [\"gherkin-feature\"]\n```\n\n## Writing feature files into a custom output directory\n\n```python\nextensions = [\"sphinx_gherkin_feature\"]\n\ngherkin_feature_write_file = True\ngherkin_feature_output_dir = \"features\"\n```\n\nWith an HTML build, this writes files below:\n\n```text\n_build/html/features/\n```\n\nAbsolute paths are also supported when the project explicitly wants generated files outside the builder output directory:\n\n```python\ngherkin_feature_output_dir = \"/tmp/generated-features\"\n```\n\n## Syntax highlighting\n\nBy default, the extension registers a bundled Pygments lexer under `gherkin-feature` and renders directive bodies with that language alias.\n\nTo use a different alias:\n\n```python\ngherkin_feature_pygments_language = \"gherkin\"\ngherkin_feature_lexer_aliases = [\"gherkin\"]\n```\n\nTo use a lexer supplied by another package, disable bundled registration and point the rendered literal block to that alias:\n\n```python\ngherkin_feature_register_lexer = False\ngherkin_feature_pygments_language = \"gherkin\"\n```\n\nTo disable highlighting entirely:\n\n```python\ngherkin_feature_highlight = False\n```\n\n## Linting\n\nWhen `gherkin_feature_lint = True`, the extension imports the real upstream package:\n\n```python\nfrom gherkin_lint.gherkin_lint import GherkinLint\n```\n\nThe Sphinx directive receives feature scripts as strings. The bridge therefore accepts strings and maps them to whatever API the installed upstream release exposes:\n\n1. `lint_text(code, source_name=...)`, if present\n2. `lint_string(code, source_name=...)`, if present\n3. `lint_lines(lines, source_name=...)`, if present\n4. `lint_file(path)` via a temporary `.feature` file\n\nFor `procitec/gherkin-lint` release `v26.1.1`, the file-based path is expected. No patched or vendored copy of `gherkin-lint` is used by this package.\n\n## Development with uv\n\nCreate or update the local environment:\n\n```bash\nuv sync --group dev --group docs\n```\n\nRun tests:\n\n```bash\nuv run pytest\n```\n\nRun lint checks:\n\n```bash\nuv run ruff check src tests\n```\n\nBuild the example documentation:\n\n```bash\nuv run sphinx-build -b html docs docs/_build/html\n```\n\nBuild source distribution and wheel:\n\n```bash\nuv build\n```\n\nCreate or refresh the lockfile when you want to commit a local dependency snapshot:\n\n```bash\nuv lock\n```\n\nPublish, after configuring credentials:\n\n```bash\nuv publish\n```\n\n## Project layout\n\n```text\nsrc/sphinx_gherkin_feature/\n  __init__.py      Sphinx setup and config registration\n  directives.py    gherkin:feature directive\n  domain.py        gherkin domain\n  lexer.py         bundled Pygments lexer\n  lint.py          optional gherkin-lint bridge\n  writer.py        build-finished file writer\n```\n\n## Optional gherkin-lint string API\n\n`gherkin_feature_lint = True` integrates with `procitec/gherkin-lint`.\n\nThe preferred interface is now an in-memory API on `gherkin-lint`:\n\n```python\nerrors = linter.lint_text(code, source_name=\"login.feature\")\n```\n\nThe Sphinx bridge calls `lint_text(...)` when available, then falls back to\n`lint_string(...)`, and finally to the older `lint_file(...)` API via a temporary\n`.feature` file. A proposed upstream patch for `gherkin-lint` is included in\n`external/gherkin-lint-string-api/`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocitec%2Fsphinx-gherkin-feature","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprocitec%2Fsphinx-gherkin-feature","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocitec%2Fsphinx-gherkin-feature/lists"}