sphinx-hackerrank 2026.10.30.1__tar.gz

sphinx_hackerrank-2026.10.30.1/.gitattributes

@@ -0,0 +1 @@
+*.rst conflict-marker-size=32

sphinx_hackerrank-2026.10.30.1/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13', '3.14']
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+      - run: uv run --locked --python ${{ matrix.python }} pytest --cov --cov-report=term-missing
+      - run: uv build
+      - run: uv run twine check dist/*
+      - name: Install the wheel and build outside the checkout
+        run: uv run --python ${{ matrix.python }} python tests/wheel_smoke.py
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+  sphinx-8:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+      - run: uv run --python 3.12 --with 'sphinx==8.2.3' pytest --cov --cov-report=term-missing

sphinx_hackerrank-2026.10.30.1/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish
+        required: true
+permissions:
+  contents: read
+jobs:
+  publish:
+    if: vars.PYPI_PUBLISH_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.tag || github.ref_name }}
+      - uses: astral-sh/setup-uv@v7
+      - run: uv run pytest --cov --cov-report=term-missing
+      - run: uv build
+      - run: uv run twine check dist/*
+      - run: uv run python tests/wheel_smoke.py
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

sphinx_hackerrank-2026.10.30.1/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+dist/
+build/
+*.egg-info/

sphinx_hackerrank-2026.10.30.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rippling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_hackerrank-2026.10.30.1/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: sphinx-hackerrank
+Version: 2026.10.30.1
+Summary: Build portable HackerRank interviewer mini-maps from Sphinx documentation
+Project-URL: Source, https://github.com/adamtheturtle/sphinx-hackerrank
+Project-URL: Issues, https://github.com/adamtheturtle/sphinx-hackerrank/issues
+Author-email: Adam Dangoor <adamdangoor@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: pyyaml>=6
+Requires-Dist: sphinx-jinja2>=0.0.1
+Requires-Dist: sphinx-toolbox<5,>=4.3
+Requires-Dist: sphinx<10,>=8.2
+Description-Content-Type: text/x-rst
+
+sphinx-hackerrank
+=================
+
+Build portable interviewer mini-maps from maintained Sphinx guides.
+The ``hackerrank`` builder reuses Sphinx's HTML renderer and exports one
+standalone HTML fragment per question and language, plus a local preview index.
+No HackerRank login or API token is required to build or preview.
+
+Installation
+------------
+
+.. code-block:: console
+
+   pip install sphinx-hackerrank
+
+Built wheels are also published as GitHub release assets:
+
+.. code-block:: console
+
+   pip install https://github.com/adamtheturtle/sphinx-hackerrank/releases/download/2026.10.30.1/sphinx_hackerrank-2026.10.30.1-py3-none-any.whl
+
+Enable the installed extension in ``conf.py``:
+
+.. code-block:: python
+
+   extensions = ["sphinx_hackerrank"]
+
+No ``sys.path`` changes are needed.
+
+Authoring
+---------
+
+Keep the full guide and its mini-map RST beside each other. Include native
+sections by exact heading path or an existing RST section label:
+
+.. code-block:: rst
+
+   .. container:: hr-mini-map mini-map-python
+
+      .. collapse:: Prompt
+
+         .. mini-map-section:: widgets.rst
+            :section: Part 1 / Prompt
+            :language: python
+
+Use ``:section: #widget-prompt`` for a labelled section and
+``:include-heading:`` to retain the selected section's heading.
+Nested headings become rubrics inside disclosures. Missing or ambiguous
+selections are reported as directive errors; build with ``-W`` to reject them.
+The guide does not need extraction markers or duplicated content.
+
+The directive uses native includes, substitutions, and the guide's existing
+Jinja templates. Variants are cached within each mini-map read and discarded
+before Sphinx persists the document tree. Guide and included-file dependencies
+are tracked for incremental builds.
+
+Language contexts
+-----------------
+
+Configure how each language renders the guide's Jinja context:
+
+.. code-block:: python
+
+   hackerrank_jinja_context = "snippets"
+   hackerrank_languages = {
+       "python": {
+           "name": "Python",
+           "context": {"variants": [{"name": "Python", "lexer": "python"}]},
+       },
+   }
+
+``context`` overrides values in the named Jinja context while that variant is
+parsed. The original configuration is restored afterwards.
+``name`` identifies redundant language disclosures to flatten in copied content.
+All other part, category, and test-alternative disclosures remain intact.
+
+By default, admonitions are omitted within ``hr-mini-map`` containers.
+Set ``hackerrank_exclude_admonitions = False`` to retain them.
+The original guide's admonitions remain unchanged.
+
+Question mappings
+-----------------
+
+Create a mapping beside each mini-map, such as ``widgets-mini-map.yml`` beside
+``widgets-mini-map.rst``:
+
+.. code-block:: yaml
+
+   version: 1
+   questions:
+     - language: python
+       name: Widgets - Python
+
+The default ``hackerrank_manifest_pattern`` is ``**/*-mini-map.yml``, relative
+to Sphinx's source directory. Nested directories and custom source layouts are
+supported. Extra fields such as question IDs can be managed by your publishing
+tool; the builder reads only the language and name.
+
+Build and preview
+-----------------
+
+.. code-block:: console
+
+   sphinx-build -W -b hackerrank docs build/hackerrank
+
+Open ``build/hackerrank/mini-maps/index.html`` to select a question and language.
+Each preview uses the same self-contained HTML that can be saved as HackerRank
+interviewer notes. Native disclosure elements work without JavaScript.
+The builder also produces ordinary themed HTML pages. The extension's directives
+work in the standard ``html`` builder too.
+
+Sphinx's native ``only`` directive can select ``builder_hackerrank``,
+``builder_html``, or the shared ``html`` format tag.
+
+Source links
+------------
+
+By default, links to full guide pages point back into the local HTML build.
+To target a hosted documentation or source site, configure:
+
+.. code-block:: python
+
+   hackerrank_source_url = "https://example.org/guides/"
+   hackerrank_source_suffix = ".html"
+   hackerrank_source_anchors = True
+
+A source repository can use a different suffix, such as ``.rst``, and disable
+anchors. External URLs and links within a fragment are retained.
+
+Publishing
+----------
+
+Publishing is separate from rendering. This package does not call the HackerRank
+API or manage credentials, question identities, candidate prompts, or projects.
+Your publishing tool can read the generated fragments and verify saved notes.
+
+Development
+-----------
+
+.. code-block:: console
+
+   uv run pytest --cov --cov-report=term-missing
+   uv run ruff check .
+   uv run ruff format --check .
+   uv build
+   uv run python tests/wheel_smoke.py
+
+The minimal example under ``examples/minimal/manual`` uses a custom Jinja context
+and nested guide files. The wheel smoke test installs the built wheel into a
+fresh environment and builds that example outside the checkout.
+
+To release, update the version in ``pyproject.toml`` and
+``src/sphinx_hackerrank/__init__.py``, then publish a matching GitHub release.
+The release workflow builds and checks distributions before uploading with a
+PyPI trusted publisher configured for ``release.yml`` and environment ``release``.
+Set the repository variable ``PYPI_PUBLISH_ENABLED`` to ``true`` after configuring
+the publisher. The workflow can also be dispatched with a release ``tag``.
+
+License
+-------
+
+MIT. See ``LICENSE``.

sphinx_hackerrank-2026.10.30.1/README.rst

@@ -0,0 +1,162 @@
+sphinx-hackerrank
+=================
+
+Build portable interviewer mini-maps from maintained Sphinx guides.
+The ``hackerrank`` builder reuses Sphinx's HTML renderer and exports one
+standalone HTML fragment per question and language, plus a local preview index.
+No HackerRank login or API token is required to build or preview.
+
+Installation
+------------
+
+.. code-block:: console
+
+   pip install sphinx-hackerrank
+
+Built wheels are also published as GitHub release assets:
+
+.. code-block:: console
+
+   pip install https://github.com/adamtheturtle/sphinx-hackerrank/releases/download/2026.10.30.1/sphinx_hackerrank-2026.10.30.1-py3-none-any.whl
+
+Enable the installed extension in ``conf.py``:
+
+.. code-block:: python
+
+   extensions = ["sphinx_hackerrank"]
+
+No ``sys.path`` changes are needed.
+
+Authoring
+---------
+
+Keep the full guide and its mini-map RST beside each other. Include native
+sections by exact heading path or an existing RST section label:
+
+.. code-block:: rst
+
+   .. container:: hr-mini-map mini-map-python
+
+      .. collapse:: Prompt
+
+         .. mini-map-section:: widgets.rst
+            :section: Part 1 / Prompt
+            :language: python
+
+Use ``:section: #widget-prompt`` for a labelled section and
+``:include-heading:`` to retain the selected section's heading.
+Nested headings become rubrics inside disclosures. Missing or ambiguous
+selections are reported as directive errors; build with ``-W`` to reject them.
+The guide does not need extraction markers or duplicated content.
+
+The directive uses native includes, substitutions, and the guide's existing
+Jinja templates. Variants are cached within each mini-map read and discarded
+before Sphinx persists the document tree. Guide and included-file dependencies
+are tracked for incremental builds.
+
+Language contexts
+-----------------
+
+Configure how each language renders the guide's Jinja context:
+
+.. code-block:: python
+
+   hackerrank_jinja_context = "snippets"
+   hackerrank_languages = {
+       "python": {
+           "name": "Python",
+           "context": {"variants": [{"name": "Python", "lexer": "python"}]},
+       },
+   }
+
+``context`` overrides values in the named Jinja context while that variant is
+parsed. The original configuration is restored afterwards.
+``name`` identifies redundant language disclosures to flatten in copied content.
+All other part, category, and test-alternative disclosures remain intact.
+
+By default, admonitions are omitted within ``hr-mini-map`` containers.
+Set ``hackerrank_exclude_admonitions = False`` to retain them.
+The original guide's admonitions remain unchanged.
+
+Question mappings
+-----------------
+
+Create a mapping beside each mini-map, such as ``widgets-mini-map.yml`` beside
+``widgets-mini-map.rst``:
+
+.. code-block:: yaml
+
+   version: 1
+   questions:
+     - language: python
+       name: Widgets - Python
+
+The default ``hackerrank_manifest_pattern`` is ``**/*-mini-map.yml``, relative
+to Sphinx's source directory. Nested directories and custom source layouts are
+supported. Extra fields such as question IDs can be managed by your publishing
+tool; the builder reads only the language and name.
+
+Build and preview
+-----------------
+
+.. code-block:: console
+
+   sphinx-build -W -b hackerrank docs build/hackerrank
+
+Open ``build/hackerrank/mini-maps/index.html`` to select a question and language.
+Each preview uses the same self-contained HTML that can be saved as HackerRank
+interviewer notes. Native disclosure elements work without JavaScript.
+The builder also produces ordinary themed HTML pages. The extension's directives
+work in the standard ``html`` builder too.
+
+Sphinx's native ``only`` directive can select ``builder_hackerrank``,
+``builder_html``, or the shared ``html`` format tag.
+
+Source links
+------------
+
+By default, links to full guide pages point back into the local HTML build.
+To target a hosted documentation or source site, configure:
+
+.. code-block:: python
+
+   hackerrank_source_url = "https://example.org/guides/"
+   hackerrank_source_suffix = ".html"
+   hackerrank_source_anchors = True
+
+A source repository can use a different suffix, such as ``.rst``, and disable
+anchors. External URLs and links within a fragment are retained.
+
+Publishing
+----------
+
+Publishing is separate from rendering. This package does not call the HackerRank
+API or manage credentials, question identities, candidate prompts, or projects.
+Your publishing tool can read the generated fragments and verify saved notes.
+
+Development
+-----------
+
+.. code-block:: console
+
+   uv run pytest --cov --cov-report=term-missing
+   uv run ruff check .
+   uv run ruff format --check .
+   uv build
+   uv run python tests/wheel_smoke.py
+
+The minimal example under ``examples/minimal/manual`` uses a custom Jinja context
+and nested guide files. The wheel smoke test installs the built wheel into a
+fresh environment and builds that example outside the checkout.
+
+To release, update the version in ``pyproject.toml`` and
+``src/sphinx_hackerrank/__init__.py``, then publish a matching GitHub release.
+The release workflow builds and checks distributions before uploading with a
+PyPI trusted publisher configured for ``release.yml`` and environment ``release``.
+Set the repository variable ``PYPI_PUBLISH_ENABLED`` to ``true`` after configuring
+the publisher. The workflow can also be dispatched with a release ``tag``.
+
+License
+-------
+
+MIT. See ``LICENSE``.

sphinx_hackerrank-2026.10.30.1/examples/minimal/manual/conf.py

@@ -0,0 +1,18 @@
+"""A standalone consumer with custom paths and Jinja context names."""
+
+extensions = ["sphinx_hackerrank"]
+project = "Widget exercise"
+exclude_patterns = []
+jinja2_contexts = {
+    "snippets": {
+        "variants": [
+            {"name": "Python", "lexer": "python", "prompt": "print('widget')"},
+            {"name": "JavaScript", "lexer": "javascript", "prompt": "console.log('widget');"},
+        ]
+    }
+}
+hackerrank_jinja_context = "snippets"
+hackerrank_languages = {
+    variant["lexer"]: {"name": variant["name"], "context": {"variants": [variant]}}
+    for variant in jinja2_contexts["snippets"]["variants"]
+}

sphinx_hackerrank-2026.10.30.1/examples/minimal/manual/index.rst

@@ -0,0 +1,7 @@
+Widget exercise
+===============
+
+.. toctree::
+
+   topics/widgets
+   topics/widgets-mini-map

sphinx_hackerrank-2026.10.30.1/examples/minimal/manual/topics/widgets-mini-map.rst

@@ -0,0 +1,28 @@
+Widget mini-map
+===============
+
+.. jinja:: snippets
+
+   {% for variant in variants %}
+
+   .. container:: hr-mini-map mini-map-{{ variant.lexer }}
+
+      .. rubric:: Widgets: {{ variant.name }}
+
+      See the :doc:`full guide <widgets>`.
+
+      .. collapse:: Part 1
+
+         .. collapse:: Prompt
+
+            .. mini-map-section:: widgets.rst
+               :section: #widget-prompt
+               :language: {{ variant.lexer }}
+
+         .. collapse:: FAQ
+
+            .. mini-map-section:: widgets.rst
+               :section: Part 1 / FAQ
+               :language: {{ variant.lexer }}
+
+   {% endfor %}

sphinx_hackerrank-2026.10.30.1/examples/minimal/manual/topics/widgets-mini-map.yml

@@ -0,0 +1,6 @@
+version: 1
+questions:
+  - language: python
+    name: Widgets - Python
+  - language: javascript
+    name: Widgets - JavaScript

sphinx_hackerrank-2026.10.30.1/examples/minimal/manual/topics/widgets.rst

@@ -0,0 +1,37 @@
+Widgets
+=======
+
+Part 1
+------
+
+.. _widget-prompt:
+
+Prompt
+~~~~~~
+
+Print a widget's name.
+
+.. jinja:: snippets
+
+   {% for variant in variants %}
+
+   .. collapse:: {{ variant.name }}
+
+      .. code-block:: {{ variant.lexer }}
+
+         {{ variant.prompt }}
+
+   {% endfor %}
+
+.. collapse:: Alternate inputs
+
+   .. code-block:: text
+
+      widget = ""
+
+.. tip:: Ask the participant to explain their choice.
+
+FAQ
+~~~
+
+The widget's name is always a string.

sphinx_hackerrank-2026.10.30.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sphinx-hackerrank"
+version = "2026.10.30.1"
+description = "Build portable HackerRank interviewer mini-maps from Sphinx documentation"
+readme = "README.rst"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{name = "Adam Dangoor", email = "adamdangoor@gmail.com"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Sphinx :: Extension",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "sphinx>=8.2,<10",
+    "beautifulsoup4>=4.12",
+    "pyyaml>=6",
+    "sphinx-jinja2>=0.0.1",
+    "sphinx-toolbox>=4.3,<5",
+]
+
+[project.urls]
+Source = "https://github.com/adamtheturtle/sphinx-hackerrank"
+Issues = "https://github.com/adamtheturtle/sphinx-hackerrank/issues"
+
+[dependency-groups]
+dev = ["pytest>=9", "pytest-cov>=7", "ruff>=0.17", "build>=1.2", "twine>=6"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+lint.select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["sphinx_hackerrank"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+exclude_also = ["if TYPE_CHECKING:"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_hackerrank"]

sphinx_hackerrank-2026.10.30.1/src/sphinx_hackerrank/__init__.py

@@ -0,0 +1,31 @@
+"""Sphinx extension for portable HackerRank interviewer mini-maps."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sphinx_hackerrank.builder import HackerRankBuilder
+from sphinx_hackerrank.sections import MiniMapSection, discard_guide_cache, simplify_mini_map
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "2026.10.30.1"
+
+
+def setup(app: Sphinx) -> dict[str, object]:
+    """Register the builder, directive, and project-independent settings."""
+    app.setup_extension("sphinx_jinja2")
+    app.setup_extension("sphinx_toolbox.collapse")
+    app.add_config_value("hackerrank_manifest_pattern", "**/*-mini-map.yml", "env", types=str)
+    app.add_config_value("hackerrank_languages", {}, "env", types=dict)
+    app.add_config_value("hackerrank_jinja_context", "languages", "env", types=str)
+    app.add_config_value("hackerrank_source_url", None, "html", types=(str, type(None)))
+    app.add_config_value("hackerrank_source_suffix", ".html", "html", types=str)
+    app.add_config_value("hackerrank_source_anchors", True, "html", types=bool)
+    app.add_config_value("hackerrank_exclude_admonitions", True, "html", types=bool)
+    app.add_builder(HackerRankBuilder)
+    app.add_directive("mini-map-section", MiniMapSection)
+    app.connect("doctree-read", discard_guide_cache)
+    app.connect("doctree-resolved", simplify_mini_map)
+    return {"version": __version__, "parallel_read_safe": True, "parallel_write_safe": True}