More documentation updates for 3.11.0 (#3553)

* mkdocs: add string_view examples

* mkdocs: reference underlying operators

* mkdocs: add operator<=> examples

* mkdocs: fix style check issues

* mkdocs: tweak BJData page

* mkdocs: add CMake option hints to macros

* mkdocs: fix JSON_DISABLE_ENUM_SERIALIZATION definition

* mkdocs: fix link to unit-udt.cpp

* mkdocs: fix "Arbitrary Type Conversions" title

* mkdocs: link to api/macros/*.md instead of features/macros.md

* mkdocs: document JSON_DisableEnumSerialization CMake option

* mkdocs: encode required C++ standard in example files

* docset: detect gsed/sed

* docset: update index

* docset: fix CSS patching

* docset: add list_missing_pages make target

* docset: add list_removed_paths make target

* docset: replace page titles with name from index

* docset: add install target for Zeal docset browser

* Use GCC_TOOL in ci_test_documentation target

.gitignore

@@ -9,7 +9,8 @@
 
 /.idea
 /cmake-build-*
-# Visual Studio Code
+
+# Visual Studio / Visual Studio Code
 /.vs/
 /.vscode/
 /out/
@@ -21,19 +22,20 @@
 /build*/
 
 # fuzzers
-/tests/parse_*_fuzzer
 /tests/corpus_*
+/tests/parse_*_fuzzer
 
-/venv/
-/docs/mkdocs/docs/examples/
-/docs/mkdocs/docs/__pycache__/
-/docs/mkdocs/site/
-/docs/mkdocs/venv/
+# documentation
+/docs/docset/docSet.dsidx
 /docs/docset/JSON_for_Modern_C++.docset/
 /docs/docset/JSON_for_Modern_C++.tgz
+/docs/mkdocs/docs/__pycache__/
+/docs/mkdocs/docs/examples/
 /docs/mkdocs/docs/images/json.gif
+/docs/mkdocs/site/
+/docs/mkdocs/venv/
 
 # serve_header
-/serve_header.yml
 /localhost.pem
 /localhost-key.pem
+/serve_header.yml

cmake/ci.cmake

@@ -30,7 +30,7 @@ execute_process(COMMAND ${CPPCHECK_TOOL} --version OUTPUT_VARIABLE CPPCHECK_TOOL
 string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" CPPCHECK_TOOL_VERSION "${CPPCHECK_TOOL_VERSION}")
 message(STATUS "🔖 Cppcheck ${CPPCHECK_TOOL_VERSION} (${CPPCHECK_TOOL})")
 
-find_program(GCC_TOOL NAMES g++-latest g++-HEAD g++-11)
+find_program(GCC_TOOL NAMES g++-latest g++-HEAD g++-11 g++-10)
 execute_process(COMMAND ${GCC_TOOL} --version OUTPUT_VARIABLE GCC_TOOL_VERSION ERROR_VARIABLE GCC_TOOL_VERSION)
 string(REGEX MATCH "[0-9]+(\\.[0-9]+)+" GCC_TOOL_VERSION "${GCC_TOOL_VERSION}")
 message(STATUS "🔖 GCC ${GCC_TOOL_VERSION} (${GCC_TOOL})")
@@ -939,7 +939,7 @@ add_custom_target(ci_icpc
 ###############################################################################
 
 add_custom_target(ci_test_documentation
-    COMMAND make check_output_portable -j8
+    COMMAND make CXX="${GCC_TOOL}" check_output_portable -j8
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs
     COMMENT "Check that all examples compile and create the desired output"
 )

docs/Makefile

@@ -9,15 +9,18 @@ all: create_output
 # where are the example cpp files
 EXAMPLES = $(wildcard examples/*.cpp)
 
+cxx_standard = $(lastword c++11 $(filter c++%, $(subst ., ,$1)))
+
 # create output from a stand-alone example file
 %.output: %.cpp
-	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=c++11"
+	@echo "standard $(call cxx_standard $(<:.cpp=))"
+	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	rm $(<:.cpp=)
 
 # compare created output with current output of the example files
 %.test: %.cpp
-	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=c++11"
+	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	diff $@ $(<:.cpp=.output)
 	rm $(<:.cpp=) $@

docs/docset/Makefile

@@ -1,24 +1,86 @@
-JSON_for_Modern_C++.docset: Info.plist docSet.sql
-	$(MAKE) clean
+SED ?= $(shell which gsed 2>/dev/null || which sed)
+
+MKDOCS_PAGES=$(shell cd ../mkdocs/docs/ && find * -type f -name '*.md' | sort)
+
+.PHONY: all
+all: JSON_for_Modern_C++.tgz
+
+docSet.dsidx: docSet.sql
+	# generate index
+	sqlite3 docSet.dsidx <docSet.sql
+
+JSON_for_Modern_C++.docset: Info.plist docSet.dsidx
+	rm -fr JSON_for_Modern_C++.docset JSON_for_Modern_C++.tgz
 	mkdir -p JSON_for_Modern_C++.docset/Contents/Resources/Documents/
 	cp icon*.png JSON_for_Modern_C++.docset
 	cp Info.plist JSON_for_Modern_C++.docset/Contents
 	# build and copy documentation
 	$(MAKE) build -C ../mkdocs
 	cp -r ../mkdocs/site/* JSON_for_Modern_C++.docset/Contents/Resources/Documents
 	# patch CSS to hide navigation items
-	echo "\n\nheader, footer, navi, div.md-sidebar--primary, nav.md-tabs--active, a.md-content__button { display: none; }" >> "$$(ls JSON_for_Modern_C++.docset/Contents/Resources/Documents/assets/stylesheets/main.*.min.css)"
+	echo -e "\n\nheader, footer, nav.md-tabs, nav.md-tabs--active, div.md-sidebar--primary, a.md-content__button { display: none; }" >> "$$(ls JSON_for_Modern_C++.docset/Contents/Resources/Documents/assets/stylesheets/main.*.min.css)"
 	# fix spacing
-	echo "\n\ndiv.md-sidebar div.md-sidebar--secondary, div.md-main__inner { top: 0; margin-top: 0 }" >> "$$(ls JSON_for_Modern_C++.docset/Contents/Resources/Documents/assets/stylesheets/main.*.min.css)"
-	# remove "JSON for Modern C++" from page titles
-	find JSON_for_Modern_C++.docset/Contents/Resources/Documents -type f -exec gsed -i 's| - JSON for Modern C++</title>|</title>|' {} +
+	echo -e "\n\ndiv.md-sidebar div.md-sidebar--secondary, div.md-main__inner { top: 0; margin-top: 0 }" >> "$$(ls JSON_for_Modern_C++.docset/Contents/Resources/Documents/assets/stylesheets/main.*.min.css)"
+	# remove "JSON for Modern C++" from page titles (fallback)
+	find JSON_for_Modern_C++.docset/Contents/Resources/Documents -type f -exec $(SED) -i 's| - JSON for Modern C++</title>|</title>|' {} +
+	# replace page titles with name from index, if available
+	for page in $(MKDOCS_PAGES); do \
+		case "$$page" in \
+			*/index.md) path=$${page/\/index.md/} ;; \
+			*)          path=$${page/.md/}        ;; \
+		esac; \
+		title=$$(sqlite3 docSet.dsidx "SELECT name FROM searchIndex WHERE path='$$path/index.html'" | tr '\n' ',' | $(SED) -e 's/,/, /g' -e 's/, $$/\n/'); \
+		if [ "x$$title" != "x" ]; then \
+			$(SED) -i "s%<title>.*</title>%<title>$$title</title>%" "JSON_for_Modern_C++.docset/Contents/Resources/Documents/$$path/index.html"; \
+		fi \
+	done
 	# clean up
 	rm JSON_for_Modern_C++.docset/Contents/Resources/Documents/sitemap.*
-	# generate index
-	sqlite3 JSON_for_Modern_C++.docset/Contents/Resources/docSet.dsidx < docSet.sql
+	# copy index
+	cp docSet.dsidx JSON_for_Modern_C++.docset/Contents/Resources/
 
 JSON_for_Modern_C++.tgz: JSON_for_Modern_C++.docset
 	tar --exclude='.DS_Store' -cvzf JSON_for_Modern_C++.tgz JSON_for_Modern_C++.docset
 
+# install docset for Zeal documentation browser (https://zealdocs.org/)
+.PHONY: install_docset_zeal
+install_docset_zeal: JSON_for_Modern_C++.docset
+	docset_root=$${XDG_DATA_HOME:-$$HOME/.local/share}/Zeal/Zeal/docsets; \
+	rm -rf $$docset_root/JSON_for_Modern_C++.docset; \
+	mkdir -p $$docset_root; \
+	cp -r JSON_for_Modern_C++.docset $$docset_root/
+
+# list mkdocs pages missing from the docset index
+.PHONY: list_missing_pages
+list_missing_pages: docSet.dsidx
+	@for page in $(MKDOCS_PAGES); do \
+		case "$$page" in \
+			*/index.md) path=$${page/\/index.md/} ;; \
+			*)          path=$${page/.md/}        ;; \
+		esac; \
+		if [ "x$$page" != "xindex.md" -a "x$$(sqlite3 docSet.dsidx "SELECT COUNT(*) FROM searchIndex WHERE path='$$path/index.html'")" = "x0" ]; then \
+			echo $$page; \
+		fi \
+	done
+
+# list paths in the docset index without a corresponding mkdocs page
+.PHONY: list_removed_paths
+list_removed_paths: docSet.dsidx
+	@for path in $$(sqlite3 docSet.dsidx "SELECT path FROM searchIndex"); do \
+		page=$${path/\/index.html/.md}; \
+		page_index=$${path/index.html/index.md}; \
+		page_found=0; \
+		for p in $(MKDOCS_PAGES); do \
+			if [ "x$$p" = "x$$page" -o "x$$p" = "x$$page_index" ]; then \
+				page_found=1; \
+			fi \
+		done; \
+		if [ "x$$page_found" = "x0" ]; then \
+			echo $$path; \
+		fi \
+	done
+
+.PHONY: clean
 clean:
+	rm -f docSet.dsidx
 	rm -fr JSON_for_Modern_C++.docset JSON_for_Modern_C++.tgz