Skip to main content

Build Status PyPI

sphinx-hackerrank

Build portable Interviewer Guidelines from maintained Sphinx guides.

  • Reuse Sphinx’s HTML renderer.

  • Export selected guides as standalone HTML fragments, 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. Guide composition and portable 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"]

Authoring

Keep the full guide and its Interviewer Guideline RST beside each other. Declare the composition in the Interviewer Guideline RST:

.. interviewer-guideline:: guide.rst

   .. guideline-introduction::

      See the `source guide <{source_url}>`_.

   .. guideline-before:: Shared brief

   .. guideline-part:: Stage 1

      .. guideline-group:: Work

         .. guideline-select:: Brief
            :alternatives: Briefs

      .. guideline-group:: Examples

         .. guideline-select:: Cases
            :include-heading:

   .. guideline-part:: Stage 2

      .. guideline-group:: Work

         .. guideline-select:: Brief
            :alternatives: Briefs

   .. guideline-after:: Review

The package has no built-in section names, grouping rules, or introductory wording. conf.py configures the extension and explicit export requests. Each guideline’s RST owns its selections, presentation, and completeness rules. The full guide owns the selected content.

Each guideline-part names one exact source heading and contains its own groups. Every declared part must exist once, independently of its selected contents. Parts appear in declaration order, and punctuation in headings is literal. Repeat group declarations where parts share a layout. For example, Stage 1 above requires cases while Stage 2 has no cases group. Each guideline-group combines its selections under the supplied display title. Groups and selections appear in declaration order. A guideline-select is required by default and must retain content after filtering. Add :optional: for a section which may be absent or empty, and :include-heading: to retain its source heading. :alternatives: lists other accepted heading spellings, one per line. Exactly one spelling must match. Use guideline-select:: . for a part whose instructions are its own body. Separately selected descendants appear once in their own group.

guideline-before and guideline-after select shared content before or after all parts. They accept the same options as guideline-select and cannot overlap a part.

An optional guideline-introduction contains introductory RST, with {source_url} replaced by the configured guide URL. Other prose belongs in the full guide. Native include directives can share recipe declarations or selections, with dependencies tracked for incremental builds. Recipe declarations are validated and consumed before rendering. Misplaced declarations, invalid nesting, and unsupported recipe content fail the build.

The directive composes one guide in the active Sphinx context. Source selections can be nested beneath other selections without requiring parent paths in the recipe. Optional empty groups are omitted after admonitions are removed. Incomplete parts, missing required content, and ambiguous selected headings fail the build. Changing the guide, recipe, or an included file refreshes the view.

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. The source is parsed once for a composition, then all selections reuse that 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.

Explicit exports

Supply each output’s source document, CSS selector, destination, and display name:

"""Sphinx configuration."""

from sphinx_hackerrank import GuidelineExport

hackerrank_exports = [
    GuidelineExport(
        docname="widgets-interviewer-guideline",
        selector=".hr-interviewer-guideline",
        output_path="interviewer-guidelines/widgets/review.html",
        name="Widget review",
    ),
]

Each export selects a unique HTML destination inside the build directory, while the consumer prepares the source and supplies any question mappings or rendering contexts. A consumer extension can parse a recipe with sphinx_hackerrank.recipe.parse_recipe and call sphinx_hackerrank.compose_guide with a prepared document, layout, introduction, source document name, and display title. The result is a normal Sphinx container which the consumer can identify with its own CSS class and export request.

Build and preview

sphinx-build -W -b hackerrank docs build/hackerrank
  • Open build/hackerrank/interviewer-guidelines/index.html to select an exported guide.

  • 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 caller-selected 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.7

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

Built distribution (wheel)

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

Total release size: 222.4 kB

Release files / sphinx_hackerrank-2026.11.1.7.tar.gz

Download URL sphinx_hackerrank-2026.11.1.7.tar.gz
Size 199.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d6de7d9d0c3a4d98d0d06437e03ee7ffd141f8216c959b37909636a7c150463b
BLAKE2b-256 checksum
How to use checksums
ddfa7c42e2508c1a9fb0778dfed6edf811d996ce9d2d8d21358268565e899671
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.7-py3-none-any.whl

Download URL sphinx_hackerrank-2026.11.1.7-py3-none-any.whl
Size 23.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a413e7a2cbf4458f68afe43776b7470bdab8fae532abad7d8e7c3162ad100960
BLAKE2b-256 checksum
How to use checksums
74b031606589a693da32e901d35d650cfbc134b8eb508e7e92cb93509cd6907f
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.7

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