kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

gendocs.py (9535B)


      1 #!/usr/bin/env python3
      2 
      3 # This script generates a static documentation web site
      4 # by parsing the `**/*.asiidoc` files from the repository.
      5 #
      6 # Dependencies:
      7 # * Python 3
      8 # * `xdg-open` for opening the final result in a web browser.
      9 # * `antora` - a static documentation web site generator,
     10 #     https://docs.antora.org/antora/latest
     11 #
     12 # Usage:
     13 # ```console
     14 # $ ./contrib/gendocs.py
     15 # ```
     16 #
     17 # After running it should open the generated web site in a browser.
     18 #
     19 
     20 
     21 from dataclasses import dataclass
     22 from typing import Optional
     23 import glob
     24 import itertools
     25 import os
     26 import pathlib
     27 import re
     28 import shutil
     29 import subprocess
     30 
     31 # Get the script directory.
     32 script_dir = os.path.dirname(os.path.realpath(__file__))
     33 
     34 # Switch to the projects root dir.
     35 os.chdir(os.path.join(script_dir, ".."))
     36 
     37 # Recreating the final output dir to start from scratch.
     38 shutil.rmtree("doc_gen", ignore_errors=True)
     39 os.makedirs("doc_gen", exist_ok=True)
     40 
     41 # Antora fails if the repo contains broken symbolic links.
     42 # shutil.rmtree("libexec", ignore_errors=True)
     43 
     44 # Canonical Antora paths.
     45 # See: https://docs.antora.org/antora/latest/standard-directories.
     46 #      https://docs.antora.org/antora/latest/root-module-directory.
     47 os.makedirs("doc_gen/modules/ROOT/images", exist_ok=True)
     48 os.makedirs("doc_gen/modules/ROOT/pages", exist_ok=True)
     49 
     50 
     51 # Put necessary images to the Antora canonical directory.
     52 # See: https://docs.antora.org/antora/latest/images-directory.
     53 for gif_file in glob.glob("doc/*.gif"):
     54     shutil.copy(gif_file, "doc_gen/modules/ROOT/images/")
     55 
     56 
     57 # Fix links according to the Antora specification.
     58 # See: https://docs.antora.org/antora/latest/page/xref.
     59 def fix_links(path):
     60     @dataclass
     61     class Link:
     62         path: Optional[str]
     63         file: Optional[str]
     64         fragment: Optional[str]
     65         title: str
     66 
     67         def __init__(self, path, file, fragment, title):
     68             self.path = path
     69             self.file = file
     70             self.fragment = fragment
     71             self.title = title
     72 
     73     def dropwhile(predicate, string):
     74         return "".join(
     75             itertools.dropwhile(
     76                 predicate,
     77                 string,
     78             )
     79         )
     80 
     81     def dropwhileright(predicate, string):
     82         return "".join(
     83             reversed(
     84                 list(
     85                     itertools.dropwhile(
     86                         predicate,
     87                         reversed(string),
     88                     )
     89                 )
     90             )
     91         )
     92 
     93     def takewhile(predicate, string):
     94         return "".join(
     95             itertools.takewhile(
     96                 predicate,
     97                 string,
     98             )
     99         )
    100 
    101     def untag(string):
    102         no_opening = dropwhile(lambda c: c == "<", string)
    103         no_closing = dropwhileright(lambda c: c == ">", no_opening)
    104         return no_closing
    105 
    106     def parse(string):
    107         untagged = untag(string)
    108         prefix, title = untagged.split(",", 1)
    109         title = title.strip()
    110         fragment = dropwhile(lambda c: c != "#", prefix)
    111         fragment = fragment if fragment else None
    112         fragmentless = takewhile(lambda c: c != "#", prefix)
    113         segments = fragmentless.split("/")
    114         path, file = (
    115             ("/".join(segments[:-1]), segments[-1])
    116             if "/" in fragmentless
    117             else (None, fragmentless)
    118         )
    119         return Link(path, file, fragment, title)
    120 
    121     def render(link):
    122         if link.path and link.file and link.fragment == "#":
    123             return f"xref:{link.path}/{link.file}.adoc[{link.title}]"
    124         elif link.path and link.file and link.fragment:
    125             return f"xref:{link.path}/{link.file}.adoc{link.fragment}[{link.title}]"
    126         elif not link.path and link.file and link.fragment == "#":
    127             return f"xref:./{link.file}.adoc[{link.title}]"
    128         elif not link.path and link.file and link.fragment:
    129             return f"xref:./{link.file}.adoc{link.fragment}[{link.title}]"
    130         elif not link.path and link.file and not link.fragment:
    131             return f"<<{link.file},{link.title}>>"
    132         else:
    133             raise RuntimeError(f"Failed to render link: {link}")
    134 
    135     def process(m):
    136         string = m.group(0)
    137         return render(parse(string)) if "," in string else string
    138 
    139     content = None
    140 
    141     with open(path, "r") as file:
    142         content = file.read()
    143 
    144     # Fix image links according the Antora specification.
    145     # See: https://docs.antora.org/antora/latest/page/image-resource-id-examples.
    146     content = content.replace("image::doc/", "image::")
    147 
    148     with open(path, "w") as file:
    149         file.write(re.sub(r"<<[^>]+>>", process, content))
    150 
    151 
    152 # A useful documentation page.
    153 # Add the `.adoc` extension to include it into the result.
    154 shutil.copy(
    155     "VIMTOKAK",
    156     "doc_gen/modules/ROOT/pages/VIMTOKAK.adoc",
    157 )
    158 fix_links("doc_gen/modules/ROOT/pages/VIMTOKAK.adoc")
    159 
    160 for source in glob.glob("**/*.asciidoc", recursive=True):
    161     # Create directories structure matching the project's original structure.
    162     # See: https://docs.antora.org/antora/latest/pages-directory.
    163     page_dir = os.path.join(
    164         "doc_gen/modules/ROOT/pages",
    165         os.path.dirname(source),
    166     )
    167     os.makedirs(page_dir, exist_ok=True)
    168 
    169     # Copy the `asciidoc` file into the Antora `pages` directory
    170     # with the mandatory `.adoc` filename extension.
    171     adoc = os.path.join(page_dir, pathlib.Path(source).stem + ".adoc")
    172     shutil.copy(source, adoc)
    173 
    174     if source == "README.asciidoc":
    175         # Update the filename so it reflects the content.
    176         # The filename is used for navigation links.
    177         shutil.move(
    178             "doc_gen/modules/ROOT/pages/README.adoc",
    179             "doc_gen/modules/ROOT/pages/index.adoc",
    180         )
    181         adoc = "doc_gen/modules/ROOT/pages/index.adoc"
    182     elif source == "test/README.asciidoc":
    183         # The file name is used for navigation links.
    184         # Update so it reflects the content.
    185         shutil.move(
    186             "doc_gen/modules/ROOT/pages/test/README.adoc",
    187             "doc_gen/modules/ROOT/pages/test/tests.adoc",
    188         )
    189         adoc = "doc_gen/modules/ROOT/pages/test/tests.adoc"
    190     fix_links(adoc)
    191 
    192 
    193 # A navigation file for the sidebar.
    194 # See: https://docs.antora.org/antora/latest/navigation/single-list.
    195 #
    196 # TODO: Generate automatically.
    197 nav_content = """
    198 * xref:index.adoc[Getting Started]
    199 * xref:doc/pages/commands.adoc[Commands]
    200 * xref:doc/pages/expansions.adoc[Expansions]
    201 * xref:doc/pages/execeval.adoc[Exec Eval]
    202 * xref:doc/pages/scopes.adoc[Scopes]
    203 * xref:doc/pages/faces.adoc[Faces]
    204 * xref:doc/pages/buffers.adoc[Buffers]
    205 * xref:doc/pages/registers.adoc[Registers]
    206 * xref:doc/pages/mapping.adoc[Mapping]
    207 * xref:doc/pages/hooks.adoc[Hooks]
    208 * xref:doc/pages/command-parsing.adoc[Command Parsing]
    209 * xref:doc/pages/keys.adoc[Keys]
    210 * xref:doc/pages/regex.adoc[Regex]
    211 * xref:doc/pages/options.adoc[Options]
    212 * xref:doc/pages/highlighters.adoc[Highlighters]
    213 * xref:doc/pages/modes.adoc[Modes]
    214 * xref:doc/pages/keymap.adoc[KEYMAP]
    215 * xref:doc/pages/faq.adoc[FAQ]
    216 * xref:doc/pages/changelog.adoc[Changelog]
    217 * xref:doc/design.adoc[Design]
    218 * xref:doc/coding-style.adoc[Coding Style]
    219 * xref:doc/writing_scripts.adoc[Writing Scripts]
    220 * xref:doc/json_ui.adoc[JSON UI]
    221 * xref:doc/autoedit.adoc[Autoedit]
    222 * xref:doc/interfacing.adoc[Interfacing]
    223 * xref:rc/tools/lint.adoc[Linting]
    224 * xref:rc/tools/autorestore.adoc[Autorestore]
    225 * xref:rc/tools/doc.adoc[Doc]
    226 * xref:test/tests.adoc[Tests]
    227 * xref:VIMTOKAK.adoc[Vi(m) to Kakoune]
    228 """
    229 
    230 with open("doc_gen/modules/ROOT/nav.adoc", "w") as f:
    231     f.write(nav_content)
    232 
    233 # Antora component description file.
    234 # See: https://docs.antora.org/antora/latest/component-version-descriptor.
    235 antora_yml_content = """
    236 name: Kakoune
    237 nav:
    238   - modules/ROOT/nav.adoc
    239 title: Kakoune
    240 version: latest
    241 """
    242 
    243 with open("doc_gen/antora.yml", "w") as f:
    244     f.write(antora_yml_content)
    245 
    246 # Antora playbook file.
    247 # See: https://docs.antora.org/antora/latest/playbook.
    248 antora_playbook_content = """
    249 asciidoc:
    250   attributes:
    251 
    252     # Do not complain on missing attributes,
    253     # TODO: fix and turn to a fatal warning
    254     attribute-missing: skip
    255 
    256     # To fix links
    257     idprefix: ""
    258 
    259     # To fix links
    260     idseparator: "-"
    261 
    262     # Better to be reproducible, in general
    263     reproducible: true
    264 
    265     # More convenient to turn sections to IDs
    266     sectids: true
    267 
    268     # More convenient to have sections as links
    269     sectlinks: true
    270 
    271     # Do not want to miss something
    272     sectnumlevels: 5
    273 
    274     # More convenient to number the sections
    275     sectnums: true
    276 
    277     # Do not want to miss something
    278     toclevels: 5
    279 
    280   sourcemap: true
    281 
    282 content:
    283   sources:
    284   - url: ./..
    285     start_path: doc_gen
    286     branches: ["HEAD"]
    287 
    288 runtime:
    289   cache_dir: ./doc_gen/cache # More convenient for the development
    290   fetch: true # More convenient for the development
    291 
    292   log:
    293     failure_level: fatal
    294     level: warn
    295 
    296 output:
    297   clean: true # More convenient for the development
    298   dir: ./build # Simpler to have it explicit in code
    299 
    300 site:
    301   title: Kakoune Docs
    302 
    303 ui:
    304   bundle:
    305     url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    306 """
    307 
    308 with open("doc_gen/antora-playbook.yml", "w") as f:
    309     f.write(antora_playbook_content)
    310 
    311 # Finally, generate the documentation,
    312 # results will be saved to the output directory
    313 # as specified in the `antora-playbook.yml`.
    314 use_npx = shutil.which("antora") is None and shutil.which("npx") is not None
    315 subprocess.run((["npx"] if use_npx else []) + ["antora", "generate", "doc_gen/antora-playbook.yml"])
    316 subprocess.run(["xdg-open", "./doc_gen/build/Kakoune/latest/index.html"])