Rst Parser Laravel Package

Product Decisions This Supports

• Build vs. buy for RST ingestion. If any part of the roadmap involves reading reStructuredText — documentation imports, a knowledge base, migration off Sphinx/Read the Docs — this package replaces a bespoke parser with a maintained MIT-licensed one. The decision it most directly answers is "do we write a parser, embed a Python sidecar, or adopt this?"
• Docs-as-code architecture. Choosing where parsing happens: in the Laravel app at build/CLI time (this package) versus delegating to the Sphinx/docutils toolchain in Python. This is a real architectural fork with staffing and CI implications.
• Content migration scoping. A one-way RST → HTML/AST conversion layer makes "migrate the legacy RST handbook into our Laravel CMS" a tractable ticket rather than a research project. It also bounds the work: you get a parse tree, not a finished, styled page.
• Feature viability for user-authored content. If a roadmap item involves letting users write or paste RST (unlikely, but it appears in developer-tooling products), this establishes whether that is a render-pipeline feature or a security review project. Raw directives and includes make untrusted RST a different conversation entirely.
• Format support triage. Useful as a concrete data point when deciding which markup formats the product officially supports. The honest answer for most Laravel products is Markdown via league/commonmark; this package is the counter-argument only when the source corpus is already RST.
• Vendor-risk scoring. At 61 stars, zero dependents, and a Doctrine-internal origin, adopting it is a low-cost, low-commitment bet — provided it sits behind an internal interface. The decision it enables is "isolate, don't entangle."

When to Consider This Package

Adopt when:

• The source content already exists in RST. This is close to a hard prerequisite. It is a migration and interoperability tool, not a format you would choose greenfield.
• You want to stay in one runtime. Keeping PHP means no Python in the deploy image, no subprocess management, no version pinning across two ecosystems, and no separate CI job. For a Laravel team with no Python depth, this is the strongest argument.
• Processing is offline or build-time. CLI commands, queued import jobs, static site generation, seeders. Batch conversion of a docs corpus is exactly the intended workload.
• You control the input. Trusted, repository-owned content — not arbitrary uploads from end users.
• You accept the compatibility ceiling. Expect to handle Sphinx-specific roles, directives, and cross-reference semantics yourself, or normalize them upstream. This parses RST, it does not reimplement Sphinx.

Look elsewhere when:

• The content is Markdown or HTML. league/commonmark and symfony/html-sanitizer are the obvious answers; this package adds nothing.
• You need faithful Sphinx output. TOC trees, :ref: resolution, autodoc, intersphinx, and themed HTML are Sphinx features. A Python sidecar invoking real docutils/Sphinx is the lower-risk choice if fidelity to an existing Read the Docs site is the requirement.
• Rendering happens per request at scale. No Laravel service provider, no caching layer, no Blade integration — you are building the pipeline, the cache, and the sanitization yourself.
• The input is untrusted. Directive and include handling in an RST parser is an attack surface; treat this as a blocking constraint rather than a caveat.
• You need ecosystem gravity. Zero dependents and a Doctrine-internal origin mean the support surface is the issue tracker. Fine for a bounded internal tool, poor for a load-bearing product dependency.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed PHP library for reading reStructuredText — the format our existing documentation is written in. It lets us import that content into our Laravel application without adding a Python toolchain to our infrastructure or hiring for one. Cost is near zero, integration is measured in days, and because it is one-way conversion wrapped behind our own interface, the downside is contained: if we abandon it, we swap the adapter, not the product. The realistic use case is an internal documentation pipeline, not a customer-facing feature, so treat it as infrastructure efficiency rather than a growth lever.

To engineering: It parses RST into a document model and can render HTML; it does not reimplement Sphinx, so roles, directives, and cross-references from our existing docs will need normalization or custom handling. There is no Laravel package, service provider, or config — we own the wiring, caching, and output sanitization. Constraints: no Composer dependents (we are early adopters, effectively), small community, and untrusted input is out of scope. Recommendation: adopt behind a DocumentParser interface, run it only in CLI/queue contexts, and keep a Python-sidecar fallback in the architecture doc so the escape hatch is pre-agreed rather than a rewrite.