Include generated documentation in repo and dist package

Ref. eng/recordflux/RecordFlux#1822

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Style check for unsigned integer syntax (eng/recordflux/RecordFlux#1775)
 - Support for SPARK Pro 25.0 (eng/recordflux/RecordFlux#1823)
 - Support for GNAT Pro 25.0 (eng/recordflux/RecordFlux#1823)
+- `rflx doc` subcommand to open packaged HTML documentation (eng/recordflux/RecordFlux#1822)
 
 ### Fixed
 

Makefile

@@ -385,7 +385,12 @@ check_poetry: $(RFLX)
 check_unit_test_file_coverage:
 	$(POETRY) run tools/check_unit_test_file_coverage.py --source-dir $(MAKEFILE_DIR)/rflx/ --test-dir $(MAKEFILE_DIR)/tests/unit/ --ignore ide/vscode/node_modules/flatted/python
 
-check_doc: $(RFLX)
+check_doc: $(RFLX) build_html_doc
+	# Make sure checked-in docs are up to date.
+	# Trailing CRs are being ignored as Sphinx generates HTML files without the newline at the end of the file (required by POSIX).
+	# Git fixes the issue and that would otherwise make the comparison fail.
+	diff -x .buildinfo -x objects.inv --strip-trailing-cr -ur doc/user_guide/build/html/ rflx/doc/user_guide/ || (echo "Error: packaged documentation is out of date. Run 'make generate_doc' to update." >&2; exit 1)
+	diff -x .buildinfo -x objects.inv --strip-trailing-cr -ur doc/language_reference/build/html/ rflx/doc/language_reference/ || (echo "Error: packaged documentation is out of date. Run 'make generate_doc' to update." >&2; exit 1)
 	$(POETRY) run tools/check_doc.py -d doc -x doc/user_guide/gfdl.rst
 	$(POETRY) run $(MAKE) -C doc/user_guide check_help
 	$(POETRY) run tools/check_grammar.py --document doc/language_reference/language_reference.rst --verbal-map doc/language_reference/verbal_mapping.json examples/specs/*.rflx examples/apps/*/specs/*.rflx tests/data/specs/*.rflx tests/data/specs/parse_only/*.rflx
@@ -556,14 +561,22 @@ show_fuzz_parser_results: $(RFLX)
 git_hooks:
 	install -m 755 tools/pre-{commit,push} .git/hooks/
 
-.PHONY: generate generate_apps
+.PHONY: generate generate_apps generate_doc
 
 generate: $(RFLX)
 	$(POETRY) run tools/generate_spark_test_code.py
 
 generate_apps: $(RFLX)
 	$(foreach app,$(APPS),$(POETRY) run $(MAKE) -C examples/apps/$(app) generate || exit;)
 
+generate_doc: build_html_doc
+	@rm -rf rflx/doc
+	@mkdir -p rflx/doc
+	@cp -a doc/user_guide/build/html rflx/doc/user_guide
+	@cp -a doc/language_reference/build/html rflx/doc/language_reference
+	@# Do not distribute Sphinx build artifacts
+	@find rflx/doc/user_guide rflx/doc/language_reference -type f \( -name ".buildinfo" -o -name "objects.inv" \) -exec rm -v {} \;
+
 .PHONY: python_wheels_archive anod_build_dependencies anod_poetry_dependencies
 
 python_wheels_archive: TARGET_DIR=$(BUILD_DIR)

doc/language_reference/conf.py

@@ -24,7 +24,9 @@
 project = "RecordFlux"
 copyright = f"2023-{datetime.now().year}, AdaCore"  # noqa: A001, DTZ005
 author = "AdaCore"
-recordflux_version = __version__
+
+# Ignore development versions in document creation
+recordflux_version = __version__.split(".dev")[0]
 version = recordflux_version
 release = recordflux_version
 

doc/user_guide/90-appendix.rst

@@ -44,6 +44,11 @@ The `rflx run_ls` subcommand has the following options:
 .. literalinclude:: 90-rflx-run_ls--help.txt
    :language: none
 
+The `rflx doc` subcommand has the following options:
+
+.. literalinclude:: 90-rflx-doc--help.txt
+   :language: none
+
 Specification Files
 -------------------
 

doc/user_guide/90-rflx--help.txt

@@ -1,10 +1,10 @@
 usage: rflx [-h] [-q] [--version] [--no-caching] [--no-verification]
             [--max-errors NUM] [--workers NUM] [--unsafe] [--legacy-errors]
-            {check,generate,optimize,graph,validate,install,convert,run_ls}
+            {check,generate,optimize,graph,validate,install,convert,run_ls,doc}
             ...
 
 positional arguments:
-  {check,generate,optimize,graph,validate,install,convert,run_ls}
+  {check,generate,optimize,graph,validate,install,convert,run_ls,doc}
     check               check specification
     generate            generate code
     optimize            optimize generated state machine code
@@ -15,6 +15,7 @@ positional arguments:
     convert             convert foreign specifications into RecordFlux
                         specifications
     run_ls              run language server
+    doc                 open documentation
 
 options:
   -h, --help            show this help message and exit

doc/user_guide/90-rflx-doc--help.txt

@@ -0,0 +1,8 @@
+usage: rflx doc [-h] {lrm,ug}
+
+positional arguments:
+  {lrm,ug}    documentation to open: Language Reference Manual (lrm), User's
+              Guide (ug)
+
+options:
+  -h, --help  show this help message and exit

doc/user_guide/conf.py

@@ -24,7 +24,9 @@
 project = "RecordFlux"
 copyright = f"2023-{datetime.now().year}, AdaCore"  # noqa: A001, DTZ005
 author = "AdaCore"
-recordflux_version = __version__
+
+# Ignore development versions in document creation
+recordflux_version = __version__.split(".dev")[0]
 version = recordflux_version
 release = recordflux_version
 

rflx/cli.py

@@ -13,6 +13,7 @@
 from importlib.abc import Traversable
 from multiprocessing import cpu_count
 from pathlib import Path
+from typing import Final
 
 from rflx.common import assert_never
 from rflx.converter import iana
@@ -33,6 +34,7 @@
 from rflx.version import version
 
 DEFAULT_PREFIX = "RFLX"
+DOC_DIR: Final[Path] = Path(str(importlib.resources.files("rflx"))) / "doc"
 
 py_logging.basicConfig(level=py_logging.INFO, format="%(message)s")
 
@@ -424,6 +426,14 @@ def main(  # noqa: PLR0915
     parser_run_ls = subparsers.add_parser("run_ls", help="run language server")
     parser_run_ls.set_defaults(func=run_language_server)
 
+    parser_doc = subparsers.add_parser("doc", help="open documentation")
+    parser_doc.add_argument(
+        "DOCUMENT",
+        help="documentation to open: Language Reference Manual (lrm), User's Guide (ug)",
+        choices=["lrm", "ug"],
+    )
+    parser_doc.set_defaults(func=doc)
+
     args = parser.parse_args(argv[1:])
 
     if args.version:
@@ -710,6 +720,18 @@ def run_language_server(args: argparse.Namespace) -> None:
     server.start_io()
 
 
+def doc(args: argparse.Namespace) -> None:
+    assert args.DOCUMENT in ["lrm", "ug"]
+
+    base_folders = {"lrm": "language_reference", "ug": "user_guide"}
+    base_folder = base_folders[args.DOCUMENT]
+
+    subprocess.run(
+        ["xdg-open", f"file://{DOC_DIR}/{base_folder}/index.html"],
+        check=True,
+    )
+
+
 def vscode_extension() -> Traversable:
     path = importlib.resources.files("rflx") / "ide" / "vscode" / "recordflux.vsix"
     assert isinstance(path, Traversable)

rflx/doc/language_reference/_sources/index.rst.txt

@@ -0,0 +1,8 @@
+==================
+Language Reference
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   language_reference