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"])