Refactor doc building to not depend on liblkqllang anymore

Author: raph-amiard

lkql/extensions/python

@@ -4,23 +4,32 @@
 
 # -- Project information -----------------------------------------------------
 
-import os
+from os import path as P
 import sys
 import time
 
-from liblkqllang import LKQLPygmentsLexer
+# Add own dir path
+own_dir_path = P.dirname(P.realpath(__file__))
+sys.path.append(own_dir_path)
 
-dir_path = os.path.dirname(os.path.realpath(__file__))
-sys.path.append(dir_path)
+# Add lkql user_manual path into the Python path, so that we have access to the
+# lkql pygments lexer module.
+lkql_user_manual_path = P.join(
+    P.dirname(P.dirname(P.dirname(P.dirname(P.realpath(__file__))))),
+    "user_manual", "source"
+)
+
+sys.path.append(lkql_user_manual_path)
 
 import ada_pygments
 import latex_elements
+import lkql_lexer
 
 # -- General configuration ---------------------------------------------------
 
 from sphinx.highlighting import lexers
 
-lexers['lkql'] = LKQLPygmentsLexer()
+lexers['lkql'] = lkql_lexer.LKQLPygmentsLexer()
 lexers['ada'] = ada_pygments.AdaLexer()
 lexers['gpr'] = ada_pygments.GNATProjectLexer()
 
@@ -30,9 +39,8 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 
-extensions = ['lkql_doc_class',
-              'sphinx.ext.viewcode',
-              ]
+# TODO: Add back the lkql syntax check, factor it from LKQL's user manual
+extensions = ['sphinx.ext.viewcode', 'lkql_doc_class']
 templates_path = ['_templates']
 source_suffix = '.rst'
 master_doc = 'gnatcheck_rm'
@@ -57,7 +65,7 @@ def get_version():
 pygments_style = 'sphinx'
 
 html_theme = 'sphinx_rtd_theme'
-if os.path.isfile('favicon.ico'):
+if P.isfile('favicon.ico'):
     html_favicon = 'favicon.ico'
 
 html_logo = 'adacore-logo-white.png'

lkql_checker/doc/share/conf.py

@@ -20,16 +20,17 @@
 import os
 import sys
 from sphinx.highlighting import lexers
-from liblkqllang import LKQLPygmentsLexer
 
 dir_path = os.path.dirname(os.path.realpath(__file__))
 sys.path.append(dir_path)
 
+import lkql_lexer
+
 project = 'LKQL'
 copyright = '2020, AdaCore'
 author = 'Raphael Amiard'
 
-lexers['lkql'] = LKQLPygmentsLexer()
+lexers['lkql'] = lkql_lexer.LKQLPygmentsLexer()
 
 # -- General configuration ---------------------------------------------------
 

lkql_checker/doc/share/lkql_doc_class.py

@@ -11,14 +11,19 @@
 
 from sphinx.util.docutils import SphinxDirective
 
-import liblkqllang
-import traceback
+try:
+    import liblkqllang
+    LKQL_CLASSES = [
+        v for _, v in liblkqllang.__dict__.items()
+        if (type(v) == type
+            and issubclass(v, liblkqllang.LkqlNode))
+    ]
+
+except ImportError:
+    liblkqllang = None
+    LKQL_CLASSES = []
 
-lkql_classes = [
-    v for _, v in liblkqllang.__dict__.items()
-    if (type(v) == type
-        and issubclass(v, liblkqllang.LkqlNode))
-]
+import traceback
 
 
 @lru_cache
@@ -27,7 +32,7 @@ def lkql_cls_subclasses():
     Return a dict of class to direct subclasses.
     """
     res = defaultdict(list)
-    for cls in lkql_classes:
+    for cls in LKQL_CLASSES:
         if cls != liblkqllang.LkqlNode:
             res[cls.__base__].append(cls)
     return res
@@ -82,7 +87,7 @@ def process_lkql_classes_coverage(app, doctree, fromdocname):
     warnings for every non-documented class.
     """
     try:
-        for cls in lkql_classes:
+        for cls in LKQL_CLASSES:
             if not is_class_documented(cls):
                 doctree.reporter.warning(f"Class not documented: {cls}")
     except Exception as e:
@@ -130,9 +135,10 @@ def unknown_visit(self, node) -> None:
 
 
 def setup(app):
-    app.add_directive('lkql_doc_class', LkqlDocClassDirective)
-    app.connect('doctree-resolved', process_lkql_classes_coverage)
-    app.connect('doctree-resolved', check_lkql_code)
+    if liblkqllang:
+        app.add_directive('lkql_doc_class', LkqlDocClassDirective)
+        app.connect('doctree-resolved', process_lkql_classes_coverage)
+        app.connect('doctree-resolved', check_lkql_code)
 
     return {
         'version': '0.1',

user_manual/source/conf.py

@@ -0,0 +1,32 @@
+from pygments.lexer import RegexLexer, words
+from pygments import token
+
+class LKQLPygmentsLexer(RegexLexer):
+    """
+    Pygments lexer for LKQL
+    """
+    name = 'LKQL'
+    filenames = ['*.lkql']
+
+    tokens = {
+        'root': [
+            (words(('select', 'let', 'when', 'val', 'fun', 'selector',
+                    'match', 'rec', 'skip', 'is', 'in', 'true', 'false',
+                    'if', 'else', 'then', 'not', 'null', 'from'),
+                   prefix=r'\b', suffix=r'\b'),
+             token.Keyword),
+            (r"\|\".+", token.String),
+            (r"#(.?)+", token.Comment),
+            (r"(\-\>|=|\=\>|\<\=|\>\=|\=|\!\=|\+|\-|\*|\/|\&|"
+             r"\@|\||\>|\<)", token.Operator),
+            (r"\b(and|or|not)\b", token.Operator),
+            (r"\{|\}|\(|\)|\[|\]|;|\.|,", token.Punctuation),
+            (r'"(\\.|[^"])*"', token.String),
+            (r'[0-9]+', token.Number),
+            (r'_?[a-zA-Z][\w\']*', token.Name),
+            (r'_', token.Name),
+            (r'\n', token.Text),
+            (r'[^\S\n]+', token.Text),
+        ]
+    }
+