Merge pull request #3815 from raspberrypi/doxygen_fixes

Doxygen fixes

Author: nathan-contino

.gitmodules

@@ -8,5 +8,6 @@
 	branch = master
 
 [submodule "doxygentoasciidoc"]
-	path = doxygentoasciidoc
+	path = lib/doxygentoasciidoc
 	url = https://github.com/raspberrypi/doxygentoasciidoc.git
+	branch = main

Makefile

@@ -16,6 +16,7 @@ AUTO_NINJABUILD = $(BUILD_DIR)/autogenerated.ninja
 
 PICO_SDK_DIR = lib/pico-sdk
 PICO_EXAMPLES_DIR = lib/pico-examples
+DOXYGEN_TO_ASCIIDOC_DIR = lib/doxygentoasciidoc
 ALL_SUBMODULE_CMAKELISTS = $(PICO_SDK_DIR)/CMakeLists.txt $(PICO_EXAMPLES_DIR)/CMakeLists.txt
 DOXYGEN_PICO_SDK_BUILD_DIR = build-pico-sdk-docs
 DOXYGEN_XML_DIR = $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined/docs/doxygen/xml
@@ -26,7 +27,7 @@ JEKYLL_CMD = bundle exec jekyll
 
 .DEFAULT_GOAL := html
 
-.PHONY: clean run_ninja clean_ninja html serve_html clean_html build_doxygen_html clean_doxygen_html build_doxygen_adoc clean_doxygen_adoc fetch_submodules clean_submodules clean_everything
+.PHONY: clean run_ninja clean_ninja html serve_html clean_html build_doxygen_xml clean_doxygen_xml build_doxygen_adoc clean_doxygen_adoc fetch_submodules clean_submodules clean_everything
 
 $(BUILD_DIR):
 	@mkdir -p $@
@@ -51,20 +52,20 @@ $(PICO_EXAMPLES_DIR)/CMakeLists.txt: | $(PICO_SDK_DIR)/CMakeLists.txt $(PICO_EXA
 	git submodule update --init $(PICO_EXAMPLES_DIR)
 
 # Initialise doxygentoasciidoc submodule
-doxygentoasciidoc/__main__.py:
-	git submodule update --init doxygentoasciidoc
+$(DOXYGEN_TO_ASCIIDOC_DIR)/__main__.py:
+	git submodule update --init $(DOXYGEN_TO_ASCIIDOC_DIR)
 
-fetch_submodules: $(ALL_SUBMODULE_CMAKELISTS)
+fetch_submodules: $(ALL_SUBMODULE_CMAKELISTS) $(DOXYGEN_TO_ASCIIDOC_DIR)/__main__.py
 
 # Get rid of the submodules
 clean_submodules:
 	git submodule deinit --all
 
 # Create the pico-sdk Doxygen XML files
 $(DOXYGEN_XML_DIR) $(DOXYGEN_XML_DIR)/index.xml: | $(ALL_SUBMODULE_CMAKELISTS) $(DOXYGEN_PICO_SDK_BUILD_DIR)
-	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined -D PICO_EXAMPLES_PATH=../$(PICO_EXAMPLES_DIR) -D PICO_PLATFORM=combined-docs
-	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2040 -D PICO_EXAMPLES_PATH=../$(PICO_EXAMPLES_DIR) -D PICO_PLATFORM=rp2040
-	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2350 -D PICO_EXAMPLES_PATH=../$(PICO_EXAMPLES_DIR) -D PICO_PLATFORM=rp2350
+	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined -D PICO_EXAMPLES_PATH=../../$(PICO_EXAMPLES_DIR) -D PICO_NO_PICOTOOL=1 -D PICO_PLATFORM=combined-docs
+	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2040 -D PICO_EXAMPLES_PATH=../../$(PICO_EXAMPLES_DIR) -D PICO_NO_PICOTOOL=1 -D PICO_PLATFORM=rp2040
+	cmake -S $(PICO_SDK_DIR) -B $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2350 -D PICO_EXAMPLES_PATH=../../$(PICO_EXAMPLES_DIR) -D PICO_NO_PICOTOOL=1 -D PICO_PLATFORM=rp2350
 	$(MAKE) -C $(DOXYGEN_PICO_SDK_BUILD_DIR)/combined docs
 	$(MAKE) -C $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2040 docs
 	$(MAKE) -C $(DOXYGEN_PICO_SDK_BUILD_DIR)/PICO_RP2350 docs
@@ -79,13 +80,14 @@ clean_doxygen_xml:
 	rm -rf $(DOXYGEN_PICO_SDK_BUILD_DIR)
 
 # create the sdk adoc and the json file
-$(ASCIIDOC_DOXYGEN_DIR)/picosdk_index.json $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc: $(ASCIIDOC_DOXYGEN_DIR) $(DOXYGEN_XML_DIR)/index.xml doxygentoasciidoc/__main__.py doxygentoasciidoc/cli.py doxygentoasciidoc/nodes.py doxygentoasciidoc/helpers.py | $(BUILD_DIR)
+$(ASCIIDOC_DOXYGEN_DIR)/picosdk_index.json $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc: $(ASCIIDOC_DOXYGEN_DIR) $(DOXYGEN_XML_DIR)/index.xml $(DOXYGEN_TO_ASCIIDOC_DIR)/__main__.py $(DOXYGEN_TO_ASCIIDOC_DIR)/cli.py $(DOXYGEN_TO_ASCIIDOC_DIR)/nodes.py $(DOXYGEN_TO_ASCIIDOC_DIR)/helpers.py | $(BUILD_DIR) $(DOXYGEN_TO_ASCIIDOC_DIR)/requirements.txt
 	$(MAKE) clean_ninja
-	python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/index.xml > $(ASCIIDOC_DOXYGEN_DIR)/all_groups.adoc
-	python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/indexpage.xml -c > $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc
-	python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/examples_page.xml -c > $(ASCIIDOC_DOXYGEN_DIR)/examples_page.adoc
+	pip3 install -r $(DOXYGEN_TO_ASCIIDOC_DIR)/requirements.txt
+	PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/index.xml -o $(ASCIIDOC_DOXYGEN_DIR)/all_groups.adoc
+	PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/indexpage.xml -c -o $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc
+	PYTHONPATH=$(DOXYGEN_TO_ASCIIDOC_DIR)/.. python3 -m doxygentoasciidoc -f $(DOXYGEN_XML_DIR)/examples_page.xml -c -o $(ASCIIDOC_DOXYGEN_DIR)/examples_page.adoc
 	python3 $(SCRIPTS_DIR)/postprocess_doxygen_adoc.py $(ASCIIDOC_DOXYGEN_DIR)
-	-cp $(DOXYGEN_XML_DIR)/*.png $(ASCIIDOC_DOXYGEN_DIR)
+	-cp $(DOXYGEN_XML_DIR)/*.png $(ASCIIDOC_DOXYGEN_DIR) 2>/dev/null || true
 
 build_doxygen_adoc: $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc
 
@@ -94,7 +96,7 @@ clean_doxygen_adoc:
 	if [ -d $(ASCIIDOC_DOXYGEN_DIR) ]; then $(MAKE) clean_ninja; fi
 	rm -rf $(ASCIIDOC_DOXYGEN_DIR)
 
-clean_everything: clean_submodules clean_doxygen_html clean
+clean_everything: clean_submodules clean_doxygen_xml clean
 
 # AUTO_NINJABUILD contains all the parts of the ninjabuild where the rules themselves depend on other files
 $(AUTO_NINJABUILD): $(SCRIPTS_DIR)/create_auto_ninjabuild.py $(DOCUMENTATION_INDEX) $(SITE_CONFIG) | $(BUILD_DIR)

doxygentoasciidoc

@@ -16,9 +16,8 @@ def check_no_markdown(filename):
         asciidoc = re.sub(r'----\n.*?\n----', '', asciidoc, flags=re.DOTALL)
         # strip out pass-through blocks
         asciidoc = re.sub(r'\+\+\+\+\n.*?\n\+\+\+\+', '', asciidoc, flags=re.DOTALL)
-        # This is messing up the c code blocks
-        # if re.search(r'(?:^|\n)#+', asciidoc):
-        #     raise Exception("{} contains a Markdown-style header (i.e. '#' rather than '=')".format(filename))
+        if re.search(r'(?:^|\n)#+', asciidoc):
+            raise Exception("{} contains a Markdown-style header (i.e. '#' rather than '=')".format(filename))
         if re.search(r'(\[.+?\]\(.+?\))', asciidoc):
             raise Exception("{} contains a Markdown-style link (i.e. '[title](url)' rather than 'url[title]')".format(filename))
 

lib/doxygentoasciidoc

@@ -6,24 +6,24 @@
 import re
 
 def get_release_version(doxyfile_path):
-	version = "unknown"
-	with open(doxyfile_path) as f:
-		doxy_content = f.read()
-	version_search = re.search(r"(\nPROJECT_NUMBER\s*=\s*)([\d.]+)", doxy_content)
-	if version_search is not None:
-		version = version_search.group(2)
-	return version
+    version = "unknown"
+    with open(doxyfile_path) as f:
+        doxy_content = f.read()
+    version_search = re.search(r"(\nPROJECT_NUMBER\s*=\s*)([\d.]+)", doxy_content)
+    if version_search is not None:
+        version = version_search.group(2)
+    return version
 
 def write_new_data_file(output_json_file, data_obj):
-	f = open(output_json_file, 'w')
-	f.write(json.dumps(data_obj))
-	f.close()
+    f = open(output_json_file, 'w')
+    f.write(json.dumps(data_obj))
+    f.close()
 
 if __name__ == "__main__":
-	# read the doxygen config file
-	doxyfile_path = sys.argv[1]
-	# output the new data file
-	output_json_file = sys.argv[2]
-	version = get_release_version(doxyfile_path)
-	data_obj = {"pico_sdk_release": version}
-	write_new_data_file(output_json_file, data_obj)
+    # read the doxygen config file
+    doxyfile_path = sys.argv[1]
+    # output the new data file
+    output_json_file = sys.argv[2]
+    version = get_release_version(doxyfile_path)
+    data_obj = {"pico_sdk_release": version}
+    write_new_data_file(output_json_file, data_obj)