Sphinx extension for RNG -> RST

docs/extensions/rnc2html/.gitignore

@@ -0,0 +1,2 @@
+docs/_build/
+docs/reference/

docs/extensions/rnc2html/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/extensions/rnc2html/docs/README.md

@@ -0,0 +1,23 @@
+# rnc2html Extension
+
+This directory contains documentation for the `rnc2html` extension.
+
+## Usage
+
+See [index.rst](index.rst) for usage instructions and configuration details.
+
+## Example Schema
+
+An example RELAX NG XML schema is provided in [book.rng](book.rng). This schema demonstrates how to use `db:refpurpose` annotations for documentation extraction.
+
+### Testing the Example
+
+To test the extension with this example:
+
+1. Add `book.rng` to your `conf.py` configuration:
+
+   ```python
+   rnc_html_files = ["extensions/rnc2html/docs/book.rng"]
+   ```
+
+2. Run the documentation build.

docs/extensions/rnc2html/docs/book.rng

@@ -0,0 +1,40 @@
+<grammar xmlns="http://relaxng.org/ns/structure/1.0"
+         xmlns:db="http://docbook.org/ns/docbook"
+         xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0">
+
+  <start>
+    <ref name="book"/>
+  </start>
+
+  <define name="book">
+    <element name="book">
+      <!-- DocBook annotations used by the extension -->
+      <db:refpurpose>A book is the top-level element.</db:refpurpose>
+
+      <!-- Attributes with required status and documentation -->
+      <attribute name="id">
+        <a:documentation>Unique identifier for the book.</a:documentation>
+      </attribute>
+
+      <optional>
+         <attribute name="edition">
+            <a:documentation>The edition number (e.g. "1.0").</a:documentation>
+         </attribute>
+      </optional>
+
+      <!-- Content model: title followed by chapters -->
+      <element name="title">
+        <text/>
+      </element>
+
+      <oneOrMore>
+        <element name="chapter">
+          <db:refpurpose>A chapter containing text.</db:refpurpose>
+          <text/>
+        </element>
+      </oneOrMore>
+
+    </element>
+  </define>
+
+</grammar>

docs/extensions/rnc2html/docs/conf.py

@@ -0,0 +1,50 @@
+"""Configuration file for the Sphinx documentation builder."""
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from pathlib import Path
+import sys
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+"""Configuration file for the Sphinx documentation builder."""
+
+project = 'rnc2html'
+copyright = '2026, SUSE'  # noqa: A001
+author = 'SUSE'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# Add extension source to path
+# We are in docs/extensions/rnc2html/docs/
+# Extension source is in docs/extensions/rnc2html/src
+EXTENSION_ROOT = Path(__file__).parents[1] / "src"
+sys.path.insert(0, str(EXTENSION_ROOT.resolve()))
+
+extensions = [
+    "rnc2html",
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+
+# -- rnc2html options --------------------------------------------------------
+
+rnc_html_files = [
+    # "book.rng",
+    "portal-config-schema.rng",
+]
+rnc_html_multi_page = True
+rnc_html_gen_element_index = True
+rnc_html_gen_attribute_index = True

docs/extensions/rnc2html/docs/index.rst

@@ -0,0 +1,65 @@
+RNC to HTML Extension
+=====================
+
+The ``rnc2html`` extension allows you to generate HTML documentation directly from RELAX NG schemas. It supports both RELAX NG Compact Syntax (``.rnc``) and XML Syntax (``.rng``).
+
+For ``.rnc`` files, the extension automatically converts them to XML using the ``trang`` command-line tool before processing.
+
+Features
+--------
+
+- **Automatic Conversion**: Converts RNC to RNG on the fly.
+- **Documentation Extraction**: Extracts documentation from ``<db:refpurpose>`` (DocBook 5) annotations.
+- **Structured Output**: Generates tables for attributes and lists for allowed child elements.
+- **Content Models**: Displays regex-like content models (e.g., ``(title, para+)``).
+- **Multi-page Support**: Can generate separate pages for every defined element.
+
+Configuration
+-------------
+
+In your ``conf.py``:
+
+.. code-block:: python
+
+   extensions = [
+       "rnc2html",
+   ]
+
+   # List of schemas to document (relative to source directory)
+   rnc_html_files = [
+       "schemas/myschema.rnc",
+   ]
+
+   # Generate a separate page for each element?
+   rnc_html_multi_page = True
+
+Example Schema (RNG)
+--------------------
+
+The extension looks for ``db:refpurpose`` elements in the ``http://docbook.org/ns/docbook`` namespace.
+
+.. Comment 1
+    **File: book.rng**
+
+.. Comment 2
+    .. literalinclude:: product-config-schema.rng
+      :language: xml
+      :caption: Example RNG Schema with Annotations
+
+Usage in RST
+------------
+
+You can also use the directive manually in any RST file:
+
+.. code-block:: rst
+
+   .. rnc-reference:: product-config-schema.rng
+
+This will render the documentation for the schema in-place.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Generated Reference
+
+   reference/portal/index

docs/extensions/rnc2html/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "rnc2html-extension"
+version = "0.1.0"
+description = "Internal Sphinx extension for docbuild"
+dependencies = [
+    "sphinx>=9.1",
+    "lxml>=6.0.0",
+]
+requires-python = ">=3.12"
+
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+
+[dependency-groups]
+tests = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=1.0.0",
+    "pytest-cov>=6.1.1",
+]
+
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+
+[tool.uv]
+managed = true

docs/extensions/rnc2html/src/rnc2html/__init__.py

@@ -0,0 +1,33 @@
+
+"""Sphinx extension to document RELAX NG schemas."""
+
+from typing import Any
+
+from sphinx.application import Sphinx
+
+from rnc2html.builder import generate_rnc_docs
+from rnc2html.directive import RncReferenceDirective
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    """Register the extension with Sphinx."""
+    app.add_directive("rnc-reference", RncReferenceDirective)
+
+    # Configuration
+    # List of RNC files relative to source directory
+    app.add_config_value("rnc_html_files", [], "env")
+    # Whether to generate separate pages for elements
+    app.add_config_value("rnc_html_multi_page", False, "env")
+    # Whether to generate an elements index page
+    app.add_config_value("rnc_html_gen_element_index", False, "env")
+    # Whether to generate an attributes index page
+    app.add_config_value("rnc_html_gen_attribute_index", False, "env")
+
+    # Hook to generate RST files before build
+    app.connect("builder-inited", generate_rnc_docs)
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }