From: Vladimír Vondruš Date: Wed, 17 Jul 2019 16:33:41 +0000 (+0200) Subject: documentation: encode format version into search data filename. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=4c82d276c5277d83c75ef93f86c633d8a47b44be;p=blog.git documentation: encode format version into search data filename. The browser having a stale data (and a stale script) cached is okay-ish as things still mostly work, but having a stale data with a script expecting a new version or vice versa is *bad*, so prevent that by having the script always download file of the exact version it expects. This is a bit less useful with docs served from local filesystem (as the filename is encoded in HTML pages rather than in the script), but there I don't assume the browser is doing much caching so that should be okay. --- diff --git a/documentation/_search.py b/documentation/_search.py index 12e31f63..fb48e7f2 100644 --- a/documentation/_search.py +++ b/documentation/_search.py @@ -30,6 +30,10 @@ import struct from enum import Flag from types import SimpleNamespace as Empty +searchdata_format_version = 0 +searchdata_filename = f'searchdata-v{searchdata_format_version}.bin' +searchdata_filename_b85 = f'searchdata-v{searchdata_format_version}.js' + class ResultFlag(Flag): @staticmethod def from_type(flag: 'ResultFlag', type) -> 'ResultFlag': @@ -362,7 +366,7 @@ def serialize_search_data(trie: Trie, map: ResultMap, symbol_count, merge_subtre serialized_trie = trie.serialize(merge_subtrees=merge_subtrees) serialized_map = map.serialize(merge_prefixes=merge_prefixes) # magic header, version, symbol count, offset of result map - return search_data_header_struct.pack(b'MCS', 0, symbol_count, len(serialized_trie) + 10) + serialized_trie + serialized_map + return search_data_header_struct.pack(b'MCS', searchdata_format_version, symbol_count, len(serialized_trie) + 10) + serialized_trie + serialized_map def base85encode_search_data(data: bytearray) -> bytearray: return (b"/* Generated by https://mcss.mosra.cz/documentation/doxygen/. Do not edit. */\n" + @@ -490,7 +494,7 @@ def pretty_print_map(serialized: bytes, *, entryTypeClass, colors=False): def pretty_print(serialized: bytes, *, entryTypeClass, show_merged=False, show_lookahead_barriers=True, colors=False): magic, version, symbol_count, map_offset = search_data_header_struct.unpack_from(serialized) assert magic == b'MCS' - assert version == 0 + assert version == searchdata_format_version pretty_trie, stats = pretty_print_trie(serialized[search_data_header_struct.size:map_offset], show_merged=show_merged, show_lookahead_barriers=show_lookahead_barriers, colors=colors) pretty_map = pretty_print_map(serialized[map_offset:], entryTypeClass=entryTypeClass, colors=colors) diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 388befb8..9d56e271 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -47,7 +47,7 @@ from pygments import highlight from pygments.formatters import HtmlFormatter from pygments.lexers import TextLexer, BashSessionLexer, get_lexer_by_name, find_lexer_class_for_filename -from _search import ResultFlag, ResultMap, Trie, serialize_search_data, base85encode_search_data +from _search import ResultFlag, ResultMap, Trie, serialize_search_data, base85encode_search_data, searchdata_filename, searchdata_filename_b85, searchdata_format_version sys.path.append(os.path.join(os.path.dirname(os.path.realpath(__file__)), '../plugins')) import dot2svg @@ -3498,6 +3498,7 @@ def run(doxyfile, templates=default_templates, wildcard=default_wildcard, index_ rendered = template.render(index=parsed.index, DOXYGEN_VERSION=parsed.version, FILENAME=file, + SEARCHDATA_FORMAT_VERSION=searchdata_format_version, **state.doxyfile) output = os.path.join(html_output, file) @@ -3516,6 +3517,7 @@ def run(doxyfile, templates=default_templates, wildcard=default_wildcard, index_ rendered = template.render(compound=parsed.compound, DOXYGEN_VERSION=parsed.version, FILENAME=parsed.compound.url, + SEARCHDATA_FORMAT_VERSION=searchdata_format_version, **state.doxyfile) output = os.path.join(html_output, parsed.compound.url) @@ -3542,6 +3544,7 @@ def run(doxyfile, templates=default_templates, wildcard=default_wildcard, index_ rendered = template.render(compound=compound, DOXYGEN_VERSION='0', FILENAME='index.html', + SEARCHDATA_FORMAT_VERSION=searchdata_format_version, **state.doxyfile) output = os.path.join(html_output, 'index.html') with open(output, 'wb') as f: @@ -3558,10 +3561,10 @@ def run(doxyfile, templates=default_templates, wildcard=default_wildcard, index_ data = build_search_data(state, add_lookahead_barriers=search_add_lookahead_barriers, merge_subtrees=search_merge_subtrees, merge_prefixes=search_merge_prefixes) if state.doxyfile['M_SEARCH_DOWNLOAD_BINARY']: - with open(os.path.join(html_output, "searchdata.bin"), 'wb') as f: + with open(os.path.join(html_output, searchdata_filename), 'wb') as f: f.write(data) else: - with open(os.path.join(html_output, "searchdata.js"), 'wb') as f: + with open(os.path.join(html_output, searchdata_filename_b85), 'wb') as f: f.write(base85encode_search_data(data)) # OpenSearch metadata, in case we have the base URL diff --git a/documentation/python.py b/documentation/python.py index 27ad2d1e..e6436e1b 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -51,6 +51,8 @@ from docutils.transforms import Transform import jinja2 +from _search import searchdata_format_version + sys.path.append(os.path.join(os.path.dirname(os.path.realpath(__file__)), '../plugins')) import m.htmlsanity @@ -1236,7 +1238,9 @@ def extract_data_doc(state: State, parent, path: List[str], data): def render(config, template: str, page, env: jinja2.Environment): template = env.get_template(template) - rendered = template.render(page=page, URL=page.url, **config) + rendered = template.render(page=page, + URL=page.url, + SEARCHDATA_FORMAT_VERSION=searchdata_format_version, **config) with open(os.path.join(config['OUTPUT'], page.filename), 'wb') as f: f.write(rendered.encode('utf-8')) # Add back a trailing newline so we don't need to bother with diff --git a/documentation/search.js b/documentation/search.js index 69e055f8..423f5e1c 100644 --- a/documentation/search.js +++ b/documentation/search.js @@ -25,6 +25,8 @@ "use strict"; /* it summons the Cthulhu in a proper way, they say */ var Search = { + formatVersion: 0, /* the data filename contains this number too */ + trie: null, map: null, dataSize: 0, @@ -65,7 +67,7 @@ var Search = { return false; } - if(view.getUint8(3) != 0) { + if(view.getUint8(3) != this.formatVersion) { console.error("Invalid search data version"); return false; } @@ -112,11 +114,11 @@ var Search = { return true; }, - download: /* istanbul ignore next */ function(url) { + download: /* istanbul ignore next */ function(urlBase) { var req = window.XDomainRequest ? new XDomainRequest() : new XMLHttpRequest(); if(!req) return; - req.open("GET", url, true); + req.open("GET", urlBase + "searchdata-v" + this.formatVersion + ".bin", true); req.responseType = 'arraybuffer'; req.onreadystatechange = function() { if(req.readyState != 4) return; diff --git a/documentation/templates/doxygen/base.html b/documentation/templates/doxygen/base.html index 03273ead..5ef2a7bc 100644 --- a/documentation/templates/doxygen/base.html +++ b/documentation/templates/doxygen/base.html @@ -140,10 +140,10 @@ {% if M_SEARCH_DOWNLOAD_BINARY %} {% else %} - + {% endif %} {% endif %} {% if M_PAGE_FINE_PRINT %} @@ -166,3 +166,4 @@ {#- sanity checks for variables that should be always defined -#} {% if FILENAME is not defined %}{{ FILENAME.is_not_defined_the_script_is_broken }}{% endif %} {% if DOXYGEN_VERSION is not defined %}{{ DOXYGEN_VERSION.is_not_defined_the_script_is_broken }}{% endif %} +{% if SEARCHDATA_FORMAT_VERSION is defined %}{{ SEARCHDATA_FORMAT_VERSION.is_not_defined_the_script_is_broken }}{% endif %} diff --git a/documentation/templates/python/base.html b/documentation/templates/python/base.html index a3dd8198..b6ca07c6 100644 --- a/documentation/templates/python/base.html +++ b/documentation/templates/python/base.html @@ -132,10 +132,10 @@ {% if SEARCH_DOWNLOAD_BINARY %} {% else %} - + {% endif %} {% endif %} {% if FINE_PRINT %} @@ -157,3 +157,4 @@ {#- sanity checks for variables that should be always defined -#} {% if URL is not defined %}{{ URL.is_not_defined_the_script_is_broken }}{% endif %} +{% if SEARCHDATA_FORMAT_VERSION is defined %}{{ SEARCHDATA_FORMAT_VERSION.is_not_defined_the_script_is_broken }}{% endif %} diff --git a/documentation/test_doxygen/layout/pages.html b/documentation/test_doxygen/layout/pages.html index 55d0dedc..57019fed 100644 --- a/documentation/test_doxygen/layout/pages.html +++ b/documentation/test_doxygen/layout/pages.html @@ -112,7 +112,7 @@ - +