From: Vladimír Vondruš Date: Mon, 3 Jan 2022 19:13:20 +0000 (+0100) Subject: documentation/*: add a SEARCH_FILENAME_PREFIX option. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=7634c224d699e5f3663f4b19e5d9b1461042be39;p=blog.git documentation/*: add a SEARCH_FILENAME_PREFIX option. Allows to override the search data filename, which is useful when both Python and C++ documentation shares the same directory. Otherwise both would use the same search data filename and overwrite each other's data. --- diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst index d89d3898..6366f8bd 100644 --- a/doc/documentation/doxygen.rst +++ b/doc/documentation/doxygen.rst @@ -385,6 +385,11 @@ Variable Description bandwidth and initial processing time. If not set, :py:`False` is used. See `Search options`_ for more information. +:py:`SEARCH_FILENAME_PREFIX: str` Search data filename prefix. Useful to + prevent file conflicts if both C++ and + Python documentation shares the same + directory. If not set, ``searchdata`` is + used. :py:`SEARCH_HELP: str` HTML code to display as help text on empty search popup. If not set, a default message is used. Has effect only if @@ -473,6 +478,7 @@ these are not expected to be excessively large. :ini:`M_MATH_CACHE_FILE` :py:`M_MATH_CACHE_FILE` :ini:`M_SEARCH_DISABLED` :py:`SEARCH_DISABLED` :ini:`M_SEARCH_DOWNLOAD_BINARY` :py:`SEARCH_DOWNLOAD_BINARY` + :ini:`M_SEARCH_FILENAME_PREFIX` :py:`SEARCH_FILENAME_PREFIX` :ini:`M_SEARCH_HELP` :py:`SEARCH_HELP` :ini:`M_SEARCH_BASE_URL` :py:`SEARCH_BASE_URL` :ini:`M_SEARCH_EXTERNAL_URL` :py:`SEARCH_EXTERNAL_URL` diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst index 50c5ff2a..3f972ee2 100644 --- a/doc/documentation/python.rst +++ b/doc/documentation/python.rst @@ -239,6 +239,11 @@ Variable Description bandwidth and initial processing time. If not set, :py:`False` is used. See `Search options`_ for more information. +:py:`SEARCH_FILENAME_PREFIX: str` Search data filename prefix. Useful to + prevent file conflicts if both C++ and + Python documentation shares the same + directory. If not set, ``searchdata`` is + used. :py:`SEARCH_HELP: str` :abbr:`reST ` markup to display as help text on empty search popup. If not set, a default message is used. Has diff --git a/documentation/_search.py b/documentation/_search.py index a5db63c0..9c0297aa 100644 --- a/documentation/_search.py +++ b/documentation/_search.py @@ -34,8 +34,8 @@ from typing import List, Tuple # Version 0 was without the type map searchdata_format_version = 1 search_filename = f'search-v{searchdata_format_version}.js' -searchdata_filename = f'searchdata-v{searchdata_format_version}.bin' -searchdata_filename_b85 = f'searchdata-v{searchdata_format_version}.js' +searchdata_filename = f'{{search_filename_prefix}}-v{searchdata_format_version}.bin' +searchdata_filename_b85 = f'{{search_filename_prefix}}-v{searchdata_format_version}.js' class CssClass(enum.Enum): DEFAULT = 0 diff --git a/documentation/doxygen.py b/documentation/doxygen.py index c38cad96..822dca78 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -125,6 +125,7 @@ default_config = { 'SEARCH_DISABLED': False, 'SEARCH_DOWNLOAD_BINARY': False, + 'SEARCH_FILENAME_PREFIX': 'searchdata', 'SEARCH_HELP': """

Search for symbols, directories, files, pages or modules. You can omit any prefix from the symbol or file path; adding a @@ -3508,6 +3509,7 @@ def parse_doxyfile(state: State, doxyfile, values = None): ('M_SEARCH_DISABLED', 'SEARCH_DISABLED', bool), ('M_SEARCH_DOWNLOAD_BINARY', 'SEARCH_DOWNLOAD_BINARY', bool), + ('M_SEARCH_FILENAME_PREFIX', 'SEARCH_FILENAME_PREFIX', str), ('M_SEARCH_HELP', 'SEARCH_HELP', str), ('M_SEARCH_BASE_URL', 'SEARCH_BASE_URL', str), ('M_SEARCH_EXTERNAL_URL', 'SEARCH_EXTERNAL_URL', str), @@ -3768,10 +3770,10 @@ def run(state: State, *, templates=default_templates, wildcard=default_wildcard, data = build_search_data(state, add_lookahead_barriers=search_add_lookahead_barriers, merge_subtrees=search_merge_subtrees, merge_prefixes=search_merge_prefixes) if state.config['SEARCH_DOWNLOAD_BINARY']: - with open(os.path.join(html_output, searchdata_filename), 'wb') as f: + with open(os.path.join(html_output, searchdata_filename.format(search_filename_prefix=state.config['SEARCH_FILENAME_PREFIX'])), 'wb') as f: f.write(data) else: - with open(os.path.join(html_output, searchdata_filename_b85), 'wb') as f: + with open(os.path.join(html_output, searchdata_filename_b85.format(search_filename_prefix=state.config['SEARCH_FILENAME_PREFIX'])), '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 c3b059e8..8ae8347f 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -171,6 +171,7 @@ default_config = { 'SEARCH_DISABLED': False, 'SEARCH_DOWNLOAD_BINARY': False, + 'SEARCH_FILENAME_PREFIX': 'searchdata', 'SEARCH_HELP': """.. raw:: html

Search for modules, classes, functions and other @@ -2686,10 +2687,10 @@ def run(basedir, config, *, templates=default_templates, search_add_lookahead_ba # TODO: any chance we could write the file *before* it gets ever passed # to URL formatters so we can add cache buster hashes to its URL? if state.config['SEARCH_DOWNLOAD_BINARY']: - with open(os.path.join(config['OUTPUT'], config['URL_FORMATTER'](EntryType.STATIC, [os.path.join(config['OUTPUT'], state.config['SEARCH_DOWNLOAD_BINARY'] if isinstance(state.config['SEARCH_DOWNLOAD_BINARY'], str) else searchdata_filename)])[0]), 'wb') as f: + with open(os.path.join(config['OUTPUT'], config['URL_FORMATTER'](EntryType.STATIC, [os.path.join(config['OUTPUT'], state.config['SEARCH_DOWNLOAD_BINARY'] if isinstance(state.config['SEARCH_DOWNLOAD_BINARY'], str) else searchdata_filename.format(search_filename_prefix=state.config['SEARCH_FILENAME_PREFIX']))])[0]), 'wb') as f: f.write(data) else: - with open(os.path.join(config['OUTPUT'], config['URL_FORMATTER'](EntryType.STATIC, [os.path.join(config['OUTPUT'], searchdata_filename_b85)])[0]), 'wb') as f: + with open(os.path.join(config['OUTPUT'], config['URL_FORMATTER'](EntryType.STATIC, [os.path.join(config['OUTPUT'], searchdata_filename_b85.format(search_filename_prefix=state.config['SEARCH_FILENAME_PREFIX']))])[0]), 'wb') as f: f.write(base85encode_search_data(data)) # OpenSearch metadata, in case we have the base URL diff --git a/documentation/templates/doxygen/base.html b/documentation/templates/doxygen/base.html index f2129764..55a15f82 100644 --- a/documentation/templates/doxygen/base.html +++ b/documentation/templates/doxygen/base.html @@ -140,10 +140,10 @@ {% if SEARCH_DOWNLOAD_BINARY %} {% else %} - + {% endif %} {% endif %} {% if FINE_PRINT %} diff --git a/documentation/templates/python/base.html b/documentation/templates/python/base.html index 79718698..3de656b3 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 %} diff --git a/documentation/test_doxygen/search/Doxyfile b/documentation/test_doxygen/search/Doxyfile index 7d6b64e7..783fdd08 100644 --- a/documentation/test_doxygen/search/Doxyfile +++ b/documentation/test_doxygen/search/Doxyfile @@ -21,3 +21,4 @@ ALIASES = \ ##! M_LINKS_NAVBAR1 = ##! M_LINKS_NAVBAR2 = ##! M_SEARCH_DOWNLOAD_BINARY = YES +##! M_SEARCH_FILENAME_PREFIX = secretblob diff --git a/documentation/test_doxygen/test_doxyfile.py b/documentation/test_doxygen/test_doxyfile.py index 252798b6..a191420c 100644 --- a/documentation/test_doxygen/test_doxyfile.py +++ b/documentation/test_doxygen/test_doxyfile.py @@ -76,6 +76,7 @@ class Doxyfile(unittest.TestCase): 'SEARCH_DISABLED': False, 'SEARCH_DOWNLOAD_BINARY': False, + 'SEARCH_FILENAME_PREFIX': 'searchdata', 'SEARCH_BASE_URL': None, 'SEARCH_EXTERNAL_URL': None, 'SEARCH_HELP': diff --git a/documentation/test_doxygen/test_layout.py b/documentation/test_doxygen/test_layout.py index 3170c865..92ce94e7 100644 --- a/documentation/test_doxygen/test_layout.py +++ b/documentation/test_doxygen/test_layout.py @@ -34,7 +34,7 @@ class Layout(BaseTestCase): self.assertEqual(*self.actual_expected_contents('pages.html')) self.assertTrue(os.path.exists(os.path.join(self.path, 'html', 'm-dark+documentation.compiled.css'))) self.assertTrue(os.path.exists(os.path.join(self.path, 'html', search_filename))) - self.assertTrue(os.path.exists(os.path.join(self.path, 'html', searchdata_filename_b85))) + self.assertTrue(os.path.exists(os.path.join(self.path, 'html', searchdata_filename_b85.format(search_filename_prefix='searchdata')))) self.assertTrue(os.path.exists(os.path.join(self.path, 'html', 'favicon-light.png'))) class GeneratedDoxyfile(BaseTestCase): @@ -85,7 +85,7 @@ class SearchBinary(BaseTestCase): def test(self): self.run_doxygen(wildcard='indexpage.xml') self.assertEqual(*self.actual_expected_contents('index.html')) - self.assertTrue(os.path.exists(os.path.join(self.path, 'html', searchdata_filename))) + self.assertTrue(os.path.exists(os.path.join(self.path, 'html', searchdata_filename.format(search_filename_prefix='searchdata')))) class SearchOpensearch(BaseTestCase): def test(self): diff --git a/documentation/test_doxygen/test_search.py b/documentation/test_doxygen/test_search.py index 73d7d963..267ce535 100755 --- a/documentation/test_doxygen/test_search.py +++ b/documentation/test_doxygen/test_search.py @@ -37,7 +37,7 @@ class Search(IntegrationTestCase): def test(self): self.run_doxygen(index_pages=[], wildcard='*.xml') - with open(os.path.join(self.path, 'html', searchdata_filename), 'rb') as f: + with open(os.path.join(self.path, 'html', searchdata_filename.format(search_filename_prefix='secretblob')), 'rb') as f: serialized = f.read() search_data_pretty = pretty_print(serialized, entryTypeClass=EntryType)[0] #print(search_data_pretty) @@ -229,7 +229,7 @@ class LongSuffixLength(IntegrationTestCase): def test(self): self.run_doxygen(index_pages=[], wildcard='*.xml') - with open(os.path.join(self.path, 'html', searchdata_filename), 'rb') as f: + with open(os.path.join(self.path, 'html', searchdata_filename.format(search_filename_prefix='searchdata')), 'rb') as f: serialized = f.read() search_data_pretty = pretty_print(serialized, entryTypeClass=EntryType)[0] #print(search_data_pretty) diff --git a/documentation/test_doxygen/test_undocumented.py b/documentation/test_doxygen/test_undocumented.py index 2252a9af..17e89448 100644 --- a/documentation/test_doxygen/test_undocumented.py +++ b/documentation/test_doxygen/test_undocumented.py @@ -51,7 +51,7 @@ class Undocumented(IntegrationTestCase): # Test we have all symbols in search data. It's enough to assert the # count, it equal to symbol count in the header file # TODO: reuse the search data deserialization API once done - with open(os.path.join(self.path, 'html', searchdata_filename), 'rb') as f: + with open(os.path.join(self.path, 'html', searchdata_filename.format(search_filename_prefix='searchdata')), 'rb') as f: serialized = f.read() magic, version, symbol_count, map_offset, type_map_offset = search_data_header_struct.unpack_from(serialized) self.assertEqual(symbol_count, 44) diff --git a/documentation/test_python/test_layout.py b/documentation/test_python/test_layout.py index ac23f85c..a02a38a1 100644 --- a/documentation/test_python/test_layout.py +++ b/documentation/test_python/test_layout.py @@ -60,7 +60,7 @@ class Layout(BaseTestCase): self.assertTrue(os.path.exists(os.path.join(self.path, 'output/m-dark+documentation.compiled.css'))) self.assertTrue(os.path.exists(os.path.join(self.path, 'output/favicon-light.png'))) self.assertTrue(os.path.exists(os.path.join(self.path, 'output/search-v{}.js'.format(searchdata_format_version)))) - self.assertTrue(os.path.exists(os.path.join(self.path, 'output', searchdata_filename_b85))) + self.assertTrue(os.path.exists(os.path.join(self.path, 'output', searchdata_filename_b85.format(search_filename_prefix='searchdata')))) self.assertTrue(os.path.exists(os.path.join(self.path, 'output/sitemap.xml'))) class SearchBinary(BaseTestCase): @@ -71,7 +71,7 @@ class SearchBinary(BaseTestCase): }) self.assertEqual(*self.actual_expected_contents('index.html')) self.assertTrue(os.path.exists(os.path.join(self.path, 'output', 'search-v{}.js'.format(searchdata_format_version)))) - self.assertTrue(os.path.exists(os.path.join(self.path, 'output', searchdata_filename))) + self.assertTrue(os.path.exists(os.path.join(self.path, 'output', searchdata_filename.format(search_filename_prefix='searchdata')))) class SearchOpenSearch(BaseTestCase): def test(self): diff --git a/documentation/test_python/test_search.py b/documentation/test_python/test_search.py index 22c1324d..fe43d9e1 100644 --- a/documentation/test_python/test_search.py +++ b/documentation/test_python/test_search.py @@ -36,10 +36,11 @@ class Search(BaseInspectTestCase): self.run_python({ 'SEARCH_DISABLED': False, 'SEARCH_DOWNLOAD_BINARY': True, + 'SEARCH_FILENAME_PREFIX': 'secretblob', 'PYBIND11_COMPATIBILITY': True }) - with open(os.path.join(self.path, 'output', searchdata_filename), 'rb') as f: + with open(os.path.join(self.path, 'output', searchdata_filename.format(search_filename_prefix='secretblob')), 'rb') as f: serialized = f.read() search_data_pretty = pretty_print(serialized, entryTypeClass=EntryType)[0] #print(search_data_pretty) @@ -192,7 +193,7 @@ class LongSuffixLength(BaseInspectTestCase): 'PYBIND11_COMPATIBILITY': True }) - with open(os.path.join(self.path, 'output', searchdata_filename), 'rb') as f: + with open(os.path.join(self.path, 'output', searchdata_filename.format(search_filename_prefix='searchdata')), 'rb') as f: serialized = f.read() search_data_pretty = pretty_print(serialized, entryTypeClass=EntryType)[0] #print(search_data_pretty)