Add script to generate noblit.h from docs

I have the declaraions in the docs anyway. Rather than trying to
generate docs from source, we can extract the "source" from the docs.
We can also compile that file with GCC as a basic sanity check. This
transitively ensures that the docs make sense.

.gitignore

···
 
 # Built documentation.
 /site
+
+# Generated C header and precompiled C header.
+noblit.h
+noblit.h.gch
+
+# Prove state (so it can run failed tests first).
+.prove

.travis.yml

···
   - mypy --strict golden
   - mypy --strict libnoblit
 
+  # Generate the C header, then compile it to a precompiled header with GCC.
+  # This acts as a basic sanity check on the documentation.
+  - libnoblit/gen_header.py > noblit.h
+  - gcc noblit.h
+
   # Check the goldens.
   - prove --exec golden/run.py golden
 

default.nix

···
   pkgs.buildEnv {
     name = "noblit-devenv";
     paths = [
+      pkgs.gcc     # For checking the generated C header.
       pkgs.mkdocs  # For building documentation.
       pkgs.mypy    # For typechecking the Python code.
       pkgs.perl    # The "prove" test harness is part of Perl.

libnoblit/gen_header.py

···
+#!/usr/bin/env python3
+
+# Noblit -- An immutable append-only database
+# Copyright 2020 Ruud van Asseldonk
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# A copy of the License has been included in the root of the repository.
+
+"""
+Extract the noblit.h C header from the API reference.
+"""
+
+from typing import Iterable, List
+
+
+def extract_decls(lines: Iterable[str]) -> Iterable[str]:
+    """
+    Extract C declarations from code blocks in a markdown file.
+    """
+    declaration: List[str] = []
+
+    for line in lines:
+        # Four-space indented code blocks must be preceded by a blank line.
+        if line.strip() == '':
+            declaration = []
+
+        # Include content from code blocks, and join multiple lines, until the
+        # semicolon terminator.
+        if line.startswith('    '):
+            declaration.append(line.strip())
+
+            if ';' in line:
+                yield ' '.join(declaration)
+
+
+def get_decls_from_docs() -> List[str]:
+    """
+    Extract declarations from the C API reference.
+    """
+    with open('docs/reference/c.md', 'r', encoding='utf-8') as f:
+        return list(extract_decls(f))
+
+
+def main() -> None:
+    print('#ifndef _NOBLIT_H_')
+    print('#define _NOBLIT_H_')
+    print(
+        '\n/* This file was generated from docs/reference/c.md '
+        'by libnoblit/gen_header.py. */\n'
+    )
+    print('#include <stddef.h>')
+    print('#include <stdint.h>\n')
+
+    for decl in get_decls_from_docs():
+        print(decl)
+
+    print('\n#endif')
+
+
+if __name__ == '__main__':
+    main()

libnoblit/noblit.h

···
-#ifndef _NOBLIT_H_
-#define _NOBLIT_H_
-
-/* This file was generated from docs/reference/c.md by libnoblit/gen_header.py. */
-
-typedef struct Noblit noblit_t;
-noblit_t* noblit_db_read_packed(uint8_t const* fname, size_t fname_len);
-void noblit_db_free(noblit_t* db);
-
-#endif