Skip to main content

Build Status PyPI

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.

Installation

  • Requires Python 3.12+ and Sphinx 9.1.1+.

  • Installed packages need no sys.path changes.

Install from PyPI:

pip install sphinx-hackerrank

Or install a wheel from the GitHub release assets:

pip install https://github.com/adamtheturtle/sphinx-hackerrank/releases/download/2026.10.30.2/sphinx_hackerrank-2026.10.30.2-py3-none-any.whl

Enable the extension in conf.py:

"""Sphinx configuration."""

extensions = ["sphinx_hackerrank"]

Authoring

Keep the full guide and its Interviewer Guideline RST beside each other. Define the layout in the consuming project’s conf.py:

"""Sphinx configuration."""

from sphinx_hackerrank.layout import (
    GroupRequirement,
    GuidelineLayout,
    SectionGroup,
    SectionSelection,
)

hackerrank_guideline_layouts = {
    "exercise": GuidelineLayout(
        part_pattern=r"Stage [1-9]\d*",
        minimum_parts=2,
        groups=(
            SectionGroup(
                title="Work",
                sections=(SectionSelection(headings=("Brief", "Briefs")),),
            ),
            SectionGroup(
                title="Examples",
                sections=(
                    SectionSelection(
                        headings=("Cases",),
                        required=False,
                        include_heading=True,
                    ),
                ),
            ),
        ),
        trailing_sections=(SectionSelection(headings=("Review",)),),
        required_groups=(
            GroupRequirement(part_pattern=r"Stage 1", groups=("Examples",)),
        ),
        introduction="See the `source guide <{source_url}>`_.",
    ),
}

The Interviewer Guideline RST selects its consumer-defined layout:

.. interviewer-guideline:: guide.rst
   :layout: exercise

The package has no built-in section names, grouping rules, or introductory wording. part_pattern fully matches each part’s own heading, independently of its contents. minimum_parts rejects an incomplete set of parts. Groups combine selections under the supplied display title. Each SectionSelection chooses exactly one of its alternative headings. Selections are required by default and must retain content after filtering. Set required=False for optional sections and include_heading=True to retain their headings. Select headings=(".",) to use the part’s own body when there is no category heading. Separately selected descendants are excluded from that body.

leading_sections and trailing_sections select shared sections before or after the parts. They cannot overlap a part. For coding stages, required_groups can require nonempty examples while discussion stages omit them. Each requirement also has a minimum match count to detect renamed parts. introduction is RST supplied by the consumer, with {source_url} replaced by the configured guide URL. Its default is empty.

Multiple named layouts allow guides with different structures in the same project. For a single layout, set hackerrank_guideline_layout and omit :layout:.

The directive derives its page title from the guide and its languages from the adjacent question mapping. Selected sections can be nested beneath other selections without requiring parent paths in the layout. They appear once in their own group. Optional empty groups are omitted after admonitions are removed. A missing layout, missing mappings, incomplete parts, missing required content, or ambiguous selected headings fail the build. Changing the guide, mapping, or configured layout refreshes the view.

For other layouts, include native sections by exact heading path or an existing RST section label:

.. container:: hr-interviewer-guideline interviewer-guideline-python

   .. collapse:: Prompt

      .. interviewer-guideline-section:: widgets.rst
         :section: Part 1 / Prompt
         :language: python
  • Use :section: #widget-prompt to select a labelled section.

  • Add :include-heading: to retain the selected section’s heading.

  • Nested headings become rubrics inside disclosures.

  • Build with -W to reject missing or ambiguous selections as directive errors.

  • Sections come from the full guide without extraction markers or duplicated content.

  • Native includes, substitutions, and the guide’s existing Jinja templates are supported.

  • Variants are cached within each Interviewer Guideline read and discarded before Sphinx persists the document tree.

  • Guide and included-file dependencies are tracked for incremental builds.

Subsection exclusions

Keep the guide’s existing heading hierarchy when composing separate disclosures. Use :exclude-sections: to omit subsections from a parent selection:

.. interviewer-guideline-section:: widgets.rst
   :section: Part 1 / Prompt
   :language: python
   :exclude-sections: Follow up questions

.. interviewer-guideline-section:: widgets.rst
   :section: Part 1 / Prompt / Follow up questions
   :language: python
  • Exclusions are heading paths relative to the selected section, or section labels within it.

  • List multiple exclusions on separate indented lines.

  • Missing or ambiguous exclusions fail the build, as does excluding the selected section itself.

  • Exclusions affect only the copied view. The source guide and other selections retain their content.

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.

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

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.11.1
File Size Uploaded Provenance Actions
sphinx_hackerrank-2026.11.1.tar.gz 198.9 kB With provenance Details for sphinx_hackerrank-2026.11.1.tar.gz

Built distribution (wheel)

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

Total release size: 223.2 kB

Release files / sphinx_hackerrank-2026.11.1.tar.gz

Download URL sphinx_hackerrank-2026.11.1.tar.gz
Size 198.9 kB
Tags Source
SHA-256 checksum
How to use checksums
db75c12dc731fa8ef2d4e26af6373bb030019fc7b4b6c6b8a488fd7c09fa6559
BLAKE2b-256 checksum
How to use checksums
ddc9017749962629ed98557bf917dad2a9682f956d929bf4d50be36011f01eed
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 log

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

Download URL sphinx_hackerrank-2026.11.1-py3-none-any.whl
Size 24.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ad26fde1f1d709a890a0e8f7362111bcdcf8ec178360b4686a9acc4d7d97b9b
BLAKE2b-256 checksum
How to use checksums
a6632ce2d90ac22b0df5825cef06c14e592ead7a622438c5a2d374ecc9f22384
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 log

Security for sphinx-hackerrank 2026.11.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.11.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 Nov 1, 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