SCOPE-7: Specification Domain^

Summary^

Implement the spec domain in atRst to allow users to define their own domain specifications and to validate the atDoc document structure against domain expectations.

Motivation^

The specification domain satisfies two requirements for a reStructuredText parser: one is standard in the current ecosystem and one is needed but largely unheard of in the modern easy-to-write markup languages.

Docutils is the industry standard for reStructuredText parsers. Part of the reason why the language has met with such success while the Markdown standard has gradually fragmented with each successive generation of developers lies in its support for third-party tooling.

Through the extension interface, developers can add support for custom roles and directives, parsing events and processing tasks. Indeed, this is part of why a downstream project like Sphinx is possible.

Because Docutils is written in Python, as are the third-party extensions, it is fairly straight forward to plug in new features at runtime. It is not so easy a sell for our own atRst, which is written in C and on the surface would require the user to compile a custom module or otherwise upgrade the underlying Tree-sitter parser.

The first goal of the specification domain is to allow users to define custom domains with the accompanying roles and directives through Documentation driven Development.

Exempli gratia, the user writes a reStructuredText document that uses the spec domain. In the document they specify how they want to handle their custom roles and directives. A tool then compiles a JSON document that atRst can pick up to use in processing Tree-sitter nodes.

The second motivation stems from something that documentation writers need, but often rely on manual review processes and AI tools to cover: validation.

In the XML ecosystem, a user will often write an .xml document in DocBook or DITA, then check the document against an XML Schema specification, which is also written in a form of XML.

While XML isn’t quite so flexible, our plan is to have the user write an .rst document and an .rst specification file and then use a tool to check the document against the specification to ensure that all of the appropriate checks are handled.

This is similar to how Docutils checks that a directive contains required metadata and content, but it will go beyond that to cover page and section requirements. If you need all of your pages to have a meta directive or users to specify an information type and then include the correct section titles for that type, this is a way to get the build process to force the requirement.

Targets^

User Experience^

Dependencies^

Issues^