sphinx-hackerrank
Build portable Interviewer Guidelines from maintained Sphinx guides.
Reuse Sphinx’s HTML renderer.
Export one standalone HTML fragment per question and language, plus a local preview index.
Build and preview without a HackerRank login or API token.
Section loading and selection use sphinx-section-include. That extension also supplies the general-purpose include-section directive. HackerRank composition, language filtering, and HTML export live here.
Installation
Requires Python 3.12+ and Sphinx 9.1.1+.
Installed packages need no sys.path changes.
Install from PyPI:
pip install sphinx-hackerrank
Release wheels are also available from GitHub releases.
Enable the extension in conf.py:
"""Sphinx configuration."""
extensions = ["sphinx_hackerrank"]
Section selections
Use one RST composition workflow for every guide. Select a literal source heading with guideline-select:: Brief. Literal headings take precedence, including headings which contain /. When a name is repeated beneath a part, select an exact heading path such as Brief / Discussion or a standard RST section label such as #stable-discussion. Paths are relative to the selected part. Shared before/after selections are relative to the full guide. Labels must identify a section within the same scope. Missing or ambiguous required selections fail the build.
Native includes, substitutions, and the guide’s existing Jinja templates are supported. Each mapped language is parsed once for a composition, then all its selections reuse that parsed tree. Guide and included-file dependencies are tracked for incremental builds. Separately selected descendants are automatically excluded from copied parents using their resolved identities. No manual exclusion list or extraction markers are needed, and the full guide remains unchanged.
Language contexts
Configure how each language renders the guide’s Jinja context:
"""Sphinx configuration."""
hackerrank_jinja_context = "snippets"
hackerrank_languages = {
"python": {
"name": "Python",
"context": {"variants": [{"name": "Python", "lexer": "python"}]},
},
}
context overrides values in the configured Jinja context while that variant is parsed. The original configuration is restored afterwards.
name identifies redundant language disclosures to flatten in copied content.
Other part, category, and test-alternative disclosures remain intact.
Admonitions are omitted within hr-interviewer-guideline containers by default. Set hackerrank_exclude_admonitions = False to retain them. The full guide’s admonitions are unaffected.
Question mappings
Create a mapping beside each Interviewer Guideline, such as widgets-interviewer-guideline.yml beside widgets-interviewer-guideline.rst:
version: 1
questions:
- language: python
name: Widgets - Python
hackerrank_manifest_pattern defaults to **/*-interviewer-guideline.yml, relative to Sphinx’s source directory.
Nested directories and custom source layouts are supported.
The builder reads the language and name. Your publishing tool can manage extra fields such as question IDs.
Build and preview
sphinx-build -W -b hackerrank docs build/hackerrank
Open build/hackerrank/interviewer-guidelines/index.html to select a question and language.
Each preview uses the same self-contained HTML that can be saved as HackerRank Interviewer Guidelines.
Each code block has a keyboard-accessible Copy code button that preserves whitespace.
Copy buttons use JavaScript bundled with the output. Hosts must allow that script to run for the buttons to appear.
Native disclosure elements and code remain usable 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:
"""Sphinx configuration."""
hackerrank_source_url = "https://example.org/guides/"
hackerrank_source_suffix = ".html"
hackerrank_source_anchors = True
Set hackerrank_source_suffix to .rst when linking to source files.
Set hackerrank_source_anchors = False when the destination does not support anchors.
External URLs and links within a fragment are retained.
Publishing
Use a separate publishing tool to call the HackerRank API and manage credentials, question identities, candidate prompts, or projects.
Your publishing tool can read the generated fragments and verify saved Interviewer Guidelines.
Use sphinx_hackerrank.html.html_equivalent to compare generated and saved HTML. It tolerates entity encoding, block indentation, and HackerRank’s column-width formatting. Literal whitespace in code, scripts, styles, and text areas is preserved, as are spaces separating inline elements and disclosure attributes. normalize_html(html=...) exposes the normalized representation when needed. The comparison can be passed as the notes_equal callback to the HackerRank SDK’s questions.update_internal_notes() method.
Contributing
See CONTRIBUTING.rst for setup, linting, tests, and releases.
The sample under sample/source uses a custom Jinja context and nested guide files.
The wheel smoke test installs the built wheel into a fresh environment and builds that sample outside the checkout.
License
MIT. See LICENSE.
Metadata
Release files for sphinx-hackerrank 2026.11.1.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sphinx_hackerrank-2026.11.1.6.tar.gz | 202.9 kB | With provenance | Details for sphinx_hackerrank-2026.11.1.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sphinx_hackerrank-2026.11.1.6-py3-none-any.whl | Python 3 | none | any | Details for sphinx_hackerrank-2026.11.1.6-py3-none-any.whl |
Total release size: 226.9 kB
Release files / sphinx_hackerrank-2026.11.1.6.tar.gz
| Download URL | sphinx_hackerrank-2026.11.1.6.tar.gz |
|---|---|
| Size | 202.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e7bcb9e8f05fb1edf894b5b1a334ef78f92d8be78cfd823a75f7ee4bf8d944e3
|
|
BLAKE2b-256 checksum How to use checksums |
3c4a8fa4c405abe6bd1485ca7d47def575288f3daeed71406e48d4607ac6c4c2
|
| 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 Nov 1, 2026.
Transparency logRelease files / sphinx_hackerrank-2026.11.1.6-py3-none-any.whl
| Download URL | sphinx_hackerrank-2026.11.1.6-py3-none-any.whl |
|---|---|
| Size | 23.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c2703533fef99a98e2c10e960dd2cb3cb386e5c81f673251c45b8248f1c768fd
|
|
BLAKE2b-256 checksum How to use checksums |
a837fe4140bbc6227c9fd50dee615479e56ccb75fdb507570b26ebac31074dc7
|
| 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 Nov 1, 2026.
Transparency logSecurity for sphinx-hackerrank 2026.11.1.6
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.
Attestation for sphinx_hackerrank-2026.11.1.6.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 Nov 1, 2026.
Transparency logA 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.