Skip to main content

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

pip install sphinx-hackerrank

Built wheels are also published as GitHub release assets:

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:

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:

.. 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:

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:

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

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.

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

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.

Metadata

Release files for sphinx-hackerrank 2026.10.30.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinx-hackerrank 2026.10.30.1
File Size Uploaded Provenance Actions
sphinx_hackerrank-2026.10.30.1.tar.gz 89.7 kB With provenance Details for sphinx_hackerrank-2026.10.30.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sphinx-hackerrank 2026.10.30.1
File Interpreter ABI Platform Actions
sphinx_hackerrank-2026.10.30.1-py3-none-any.whl Python 3 none any Details for sphinx_hackerrank-2026.10.30.1-py3-none-any.whl

Total release size: 101.9 kB

Release files / sphinx_hackerrank-2026.10.30.1.tar.gz

Download URL sphinx_hackerrank-2026.10.30.1.tar.gz
Size 89.7 kB
Tags Source
SHA-256 checksum
How to use checksums
e7fe71bb0f144e7fe3c6141f010dd2e4cfb3abcc4f0f81f71e808b862fa5b602
BLAKE2b-256 checksum
How to use checksums
1b73ab204e53767d9e41c7558f7828f728034a0244fd2c31b42f656180f4753d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / sphinx_hackerrank-2026.10.30.1-py3-none-any.whl

Download URL sphinx_hackerrank-2026.10.30.1-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
85496a4de19cbc3f8804a9ccaa5663bb2f962d82b94c06c5de42491d90898119
BLAKE2b-256 checksum
How to use checksums
52e6e179813e41178b52f19e277e6365406f1d50697bae91c4ba89bf34946eeb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for sphinx-hackerrank 2026.10.30.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sphinx_hackerrank-2026.10.30.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page