v0.7.0

- added CSS preprocessing (closes #7) - added dynamic theme switching (closes #8) - added `html_header` config option option - added new light theme - many minor style fixes and tweaks
marzer · Sep 7, 2022 · c508fdb · c508fdb
1 parent 3077e77
commit c508fdb
Show file tree

Hide file tree

Showing 22 changed files with 3,692 additions and 957 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,128 +1,131 @@
 # Changelog
 
-## Unreleased
-- Fixed some `<link>`, `<meta>` and `<script>` tags not being included in `<head>` when a file was excluded from post-processing
-- Added `theme` command-line option
-- Added automatic generation of github links in changelog when config option `github` is set
-- Removed text from github icon on navbar (#5) (@wroyca)
-- Removed excessive spacing between article sections (#5) (@wroyca)
-- Minor visual tweaks to navbar
+## v0.7.0 - 2022-08-16
+- fixed some `<link>`, `<meta>` and `<script>` tags not being included in `<head>` when a file was excluded from post-processing
+- added `theme` command-line option
+- added `html_header` config option option
+- added automatic generation of github links in changelog when config option `github` is set
+- added new light theme
+- added dynamic switch for dark/light theme
+- removed text from github icon on navbar (#5) (@wroyca)
+- removed excessive spacing between article sections (#5) (@wroyca)
+- many minor style fixes and tweaks
 
 ## v0.6.1 - 2022-08-16
-- Fixed multi-row navbar occluding page content (#3) (@wroyca)
+- fixed multi-row navbar occluding page content (#3) (@wroyca)
 
 ## v0.6.0 - 2022-08-14
-- Fixed malformed error messages in some circumstances
-- Added builtin C++ standard macros for C++23
-- Added `changelog` config option
-- Updated cppreference.com tagfile
+- fixed malformed error messages in some circumstances
+- added builtin C++ standard macros for C++23
+- added `changelog` config option
+- updated cppreference.com tagfile
 
 ## v0.5.7 - 2022-05-17
-- Fixed being able to pass >= 33 threads to Doxygen's `NUM_PROC_THREADS`
+- fixed being able to pass >= 33 threads to Doxygen's `NUM_PROC_THREADS`
 
 ## v0.5.6 - 2022-05-14
-- Fixed path error when using `--dry`
-- Fixed `friend` keyword sometimes leaking into function return types
-- Added additional language code block aliases
-- Added `--nocleanup` to `--help` output
-- Added support for C++20's `consteval` keyword
+- fixed path error when using `--dry`
+- fixed `friend` keyword sometimes leaking into function return types
+- added additional language code block aliases
+- added `--nocleanup` to `--help` output
+- added support for C++20's `consteval` keyword
 
 ## v0.5.5 - 2022-04-16
-- Fixed C++20 concepts causing a crash in m.css (they are now skipped with a warning) (#1) (@jake-arkinstall)
+- fixed C++20 concepts causing a crash in m.css (they are now skipped with a warning) (#1) (@jake-arkinstall)
 
 ## v0.5.4 - 2022-04-15
-- Updated m.css
-- Updated emoji database
+- updated m.css
+- updated emoji database
 
 ## v0.5.3 - 2021-12-12
-- Fixed Doxygen bug that would sometimes treat keywords like `friend` as part of a function's return type
+- fixed Doxygen bug that would sometimes treat keywords like `friend` as part of a function's return type
 - Blacklisted schema 0.7.5 because [it's broken](https://github.com/keleshev/schema/issues/272)
 
 ## v0.5.2 - 2021-11-02
-- Fixed over-eager link-replacement for internal `#anchor` links
-- Added command-line options `--ppinclude` and `--ppexclude`
+- fixed over-eager link-replacement for internal `#anchor` links
+- added command-line options `--ppinclude` and `--ppexclude`
 
 ## v0.5.1 - 2021-10-09
-- Fixed over-eager link replacement causing text to be deleted
+- fixed over-eager link replacement causing text to be deleted
 
 ## v0.5.0 - 2021-09-11
-- Fixed a crash during HTML post-processing
-- Fixed `implementation_headers` not working when paths use backslashes
-- Added warnings when `implementation_headers` doesn't match anything
+- fixed a crash during HTML post-processing
+- fixed `implementation_headers` not working when paths use backslashes
+- added warnings when `implementation_headers` doesn't match anything
 
 ## v0.4.5 - 2021-06-08
-- Added command-line option `--xmlonly`
+- added command-line option `--xmlonly`
 
 ## v0.4.3 - 2021-05-31
-- Fixed regression in `[code_blocks]` functionality
-- Fixed minor issues in syntax highlighter
-- Added symbols from doxygen tagfiles to the syntax highlighter
-- Minor style tweaks
+- fixed regression in `[code_blocks]` functionality
+- fixed minor issues in syntax highlighter
+- added symbols from doxygen tagfiles to the syntax highlighter
+- minor style tweaks
 
 ## v0.4.1 - 2021-05-30
-- Fixed `.dirs` being glommed as source paths
-- Added config option `scripts`
-- Added config option `stylesheets`
-- Added config option `jquery`
-- Added `custom` theme
-- Added ability to use `HOME.md` as main page
-- Added additional fix for inline `<code>` blocks
-- Added `.poxy-toc` to table-of-contents elements
-- Added floating page table-of-contents
-- Removed m.css favicon fallback
-- Made improvements to the `light` and `dark` themes
-- Updated C++ doxygen tagfile
+- fixed `.dirs` being glommed as source paths
+- added config option `scripts`
+- added config option `stylesheets`
+- added config option `jquery`
+- added `custom` theme
+- added ability to use `HOME.md` as main page
+- added additional fix for inline `<code>` blocks
+- added `.poxy-toc` to table-of-contents elements
+- added floating page table-of-contents
+- removed m.css favicon fallback
+- made improvements to the `light` and `dark` themes
+- updated C++ doxygen tagfile
 
 ## v0.4.0 - 2021-05-29
-- Added config option `theme`
-- Added version number to CSS and javascript filenames to prevent browser cache issues
-- Added `POXY_IMPLEMENTATION_DETAIL(...)` magic macro
-- Added `POXY_IGNORE(...)` magic macro
-- Fixed alignment of nested images inside detail blocks
+- added config option `theme`
+- added version number to CSS and javascript filenames to prevent browser cache issues
+- added `POXY_IMPLEMENTATION_DETAIL(...)` magic macro
+- added `POXY_IGNORE(...)` magic macro
+- fixed alignment of nested images inside detail blocks
 
 ## v0.3.4 - 2021-05-28
-- Added basic `using` alias detection to syntax highlighter
-- Added missing badges for C++23, 26 and 29
+- added basic `using` alias detection to syntax highlighter
+- added missing badges for C++23, 26 and 29
 
 ## v0.3.3 - 2021-05-23
-- Fixed sorting of namespace and group members
-- Fixed m.css failing with new versions of doxygen due to `Doxyfile.xml`
-- Added google structured data to `\pages`
+- fixed sorting of namespace and group members
+- fixed m.css failing with new versions of doxygen due to `Doxyfile.xml`
+- added google structured data to `\pages`
 
 ## v0.3.2 - 2021-05-19
-- Fixed formatting of `<meta>` tags
-- Added config option `author`
-- Added config option `robots`
-- Added markup tag `[p]`
-- Added markup tag `[center]`
+- fixed formatting of `<meta>` tags
+- added config option `author`
+- added config option `robots`
+- added markup tag `[p]`
+- added markup tag `[center]`
 
 ## v0.3.1 - 2021-05-13
-- Added config option `macros`
-- Added command-line option `--version`
+- added config option `macros`
+- added command-line option `--version`
 
 ## v0.3.0 - 2021-05-09
 - Improved handling of m.css and Doxygen warnings and errors
-- Added command-line option `--doxygen`
-- Added command-line option `--werror`
-- Added markup tag `[set_parent_class]`
-- Added markup tag `[add_parent_class]`
-- Added markup tag `[remove_parent_class]`
-- Added config option `images`
-- Added config option `examples`
-- Added ability to specify tagfiles as URIs
+- added command-line option `--doxygen`
+- added command-line option `--werror`
+- added markup tag `[set_parent_class]`
+- added markup tag `[add_parent_class]`
+- added markup tag `[remove_parent_class]`
+- added config option `images`
+- added config option `examples`
+- added ability to specify tagfiles as URIs
 
 ## v0.2.1 - 2021-05-07
-- Fixed some minor autolinking issues
+- fixed some minor autolinking issues
 
 ## v0.2.0 - 2021-05-06
-- Added config option `source_patterns`
+- added config option `source_patterns`
 
 ## v0.1.2 - 2021-05-02
-- Fixed the Z-order of the nav bar being higher than the search overlay
-- Added `NDEBUG` to the default set of defines
+- fixed the Z-order of the nav bar being higher than the search overlay
+- added `NDEBUG` to the default set of defines
 
 ## v0.1.1 - 2021-04-26
-- Added an additional cleanup step to the HTML postprocessor
+- added an additional cleanup step to the HTML postprocessor
 
 ## v0.1.0 - 2021-04-26
 First public release :tada:
diff --git a/poxy/css.py b/poxy/css.py
@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# This file is a part of marzer/poxy and is subject to the the terms of the MIT license.
+# Copyright (c) Mark Gillard <mark.gillard@outlook.com.au>
+# See https://github.com/marzer/poxy/blob/master/LICENSE for the full license text.
+# SPDX-License-Identifier: MIT
+
+"""
+Functions for working with CSS files.
+"""
+
+import re
+from .utils import *
+
+
+RX_COMMENT = re.compile(r'''/[*].+?[*]/''', flags=re.DOTALL)
+RX_IMPORT = re.compile(r'''@import\s+url\(\s*['"](.+?)['"]\s*\)\s*;''')
+RX_MCSS_FILE = re.compile(r'(?:m|pygments)-[a-zA-Z0-9_-]+[.]css')
+RX_MCSS_THEME = re.compile(r'm-theme-([a-zA-Z0-9_-]+)[.]css')
+
+
+
+def strip_comments(text) -> str:
+	global RX_COMMENT
+	return RX_COMMENT.sub('', text)
+
+
+
+def resolve_imports(text, cwd=None, mcss_dir = None) -> tuple[str, bool]:
+	if cwd is None:
+		cwd = Path.cwd()
+	cwd = coerce_path(cwd).resolve()
+	assert_existing_directory(cwd)
+
+	if mcss_dir is None:
+		mcss_dir = find_mcss_dir()
+	else:
+		mcss_dir = coerce_path(mcss_dir).resolve()
+		assert_existing_directory(mcss_dir)
+		assert_existing_file(Path(mcss_dir, r'documentation/doxygen.py'))
+
+	had_mcss_files = False
+	def match_handler(m):
+		global RX_MCSS_THEME
+		global RX_MCSS_FILE
+		nonlocal cwd
+		nonlocal mcss_dir
+		nonlocal had_mcss_files
+
+		# skip uris altogether for now (todo: cache them? unroll google fonts?)
+		if is_uri(m[1]):
+			return m[0]
+
+		path = None
+
+		# m-css stylesheets get special handling;
+		# - first we check for any identically-named versions in poxy's data dir
+		# - then check the m-css css dir
+		had_mcss_filename = False
+		was_mcss_file = False
+		if RX_MCSS_FILE.fullmatch(m[1]):
+			path = Path(find_data_dir(), m[1])
+			if not path.exists() or not path.is_file():
+				path = Path(mcss_dir, 'css', m[1])
+				was_mcss_file = True
+			had_mcss_filename = True
+
+		# otherwise just check cwd
+		if path is None or not path.exists() or not path.is_file():
+			path = Path(cwd, m[1])
+			was_mcss_file = False
+
+		# if we still haven't found a match just leave the @import statement as it was
+		if not path.exists() or not path.is_file():
+			return m[0]
+
+		text = strip_comments(read_all_text_from_file(path, logger=True)).strip()
+		header = rf'/*==== {m[1]} {"="*(110-len(m[1]))}*/'
+		text = f'\n\n{header}\n{text}\n\n'
+
+		# more m.css special-handling
+		if was_mcss_file:
+			had_mcss_files = True
+		if had_mcss_filename:
+			# replace the :root node in the m.css theme bases with the poxy equivalent
+			theme = RX_MCSS_THEME.fullmatch(path.name)
+			if theme:
+				text = text.replace(r':root', rf'.poxy-theme-{theme[1]}')
+
+		res = resolve_imports(text, cwd=path.parent)
+		had_mcss_files = had_mcss_files or res[1]
+		return res[0]
+
+	global RX_IMPORT
+	return (RX_IMPORT.sub(match_handler, text), had_mcss_files)
+
+
+
+def minify(text) -> str:
+	text = text.replace('\t', ' ')
+	text = re.sub(r'\n[ \t]*[{]', ' {\n', text)
+	text = re.sub(r'[ \t]+\n', '\n', text)
+	text = re.sub(r'\n\n+', '\n', text)
+
+	pos = 0
+	open_brackets = []
+	while pos < len(text):
+		if text[pos:pos+2] == r'/*':
+			pos += 2
+			while pos < len(text)-1:
+				if text[pos:pos+2] == r'*/':
+					pos += 2
+					break
+				pos += 1
+		else:
+			if text[pos] == r'{':
+				open_brackets.append(pos)
+			elif text[pos] == r'}':
+				if open_brackets:
+					block_content = text[open_brackets[-1]+1:pos].strip().replace('\n', ' ')
+					block_content = re.sub(r'[ \t][ \t]+', ' ', block_content)
+					if r'{' not in block_content and r'}' not in block_content:
+						semis = 0
+						for c in block_content:
+							if c == ';':
+								semis += 1
+							if semis >= 4:
+								break
+						if semis <= 4 and len(block_content) <= 100:
+							new_block = rf'{{ {block_content} }}'
+							text = text[:open_brackets[-1]] + new_block + text[pos+1:]
+							pos = open_brackets[-1] - 1 + len(new_block) - 1
+					open_brackets.pop()
+			pos += 1
+
+	text = re.sub(r'[{]\s+?[}]', r'{}', text)
+	text = re.sub(r'[ \t][ \t]+', ' ', text)
+
+	return text
+
+
+
+def regenerate_builtin_themes(mcss_dir = None):
+	if mcss_dir is None:
+		mcss_dir = find_mcss_dir()
+	else:
+		mcss_dir = coerce_path(mcss_dir).resolve()
+		assert_existing_directory(mcss_dir)
+		assert_existing_file(Path(mcss_dir, r'documentation/doxygen.py'))
+
+	data_dir = find_data_dir()
+	output_dir = Path(data_dir, 'generated')
+	output_dir.mkdir(exist_ok=True)
+
+	THEMES = (
+		Path(data_dir, 'poxy.css'),
+	)
+	for theme_source_file in THEMES:
+		text = strip_comments(read_all_text_from_file(theme_source_file, logger=True))
+		text, had_mcss_files = resolve_imports(text, theme_source_file.parent)
+		text = re.sub(r':(before|after)', r'::\1', text)
+		text = re.sub(r':::+(before|after)', r'::\1', text)
+		text = text.replace('\r\n', '\n')
+		text = text.replace('\r', '\n')
+		text = minify(text)
+		if had_mcss_files:
+			mcss_license = read_all_text_from_file(Path(mcss_dir, 'COPYING'), logger=True).strip()
+			text = rf'''/*
+This file was automatically generated from multiple sources,
+some of which included stylesheets from mosra/m.css.
+The license for that project is as follows:
+
+{mcss_license}
+*/
+{text}
+'''
+		theme_dest_file = Path(output_dir, theme_source_file.name)
+		print(rf'Writing {theme_dest_file}')
+		with open(theme_dest_file, r'w', encoding=r'utf-8', newline='\n') as f:
+			f.write(text)
+
+
+	pass