Skip to content

Doxygen fixes #3815

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 13, 2024
Merged

Doxygen fixes #3815

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cbfff7d
Standardise whitespace and shebang in Python scripts
lurch Aug 12, 2024
1458333
Fix Makefile rule names
lurch Aug 12, 2024
e366783
Fix usage of PICO_EXAMPLES_PATH
lurch Aug 12, 2024
8a1ce26
Silence error message when there are no PNG files to copy
lurch Aug 12, 2024
5c708ab
Don't need Picotool to build doxygen, so don't waste time building it
lurch Aug 12, 2024
908528c
Move doxygentoasciidoc submodule into the lib directory, in common wi…
lurch Aug 12, 2024
6e6dca3
Bump doxygentoasciidoc submodule
lurch Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitmodules
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,6 @@
branch = master

[submodule "doxygentoasciidoc"]
path = doxygentoasciidoc
path = lib/doxygentoasciidoc
url = https://github.com/raspberrypi/doxygentoasciidoc.git
branch = main
28 changes: 15 additions & 13 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 $@
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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)
Expand Down
1 change: 0 additions & 1 deletion doxygentoasciidoc
Open in desktop
Submodule doxygentoasciidoc deleted from 70569f
1 change: 1 addition & 0 deletions lib/doxygentoasciidoc
Open in desktop
Submodule doxygentoasciidoc added at 278bc0
5 changes: 2 additions & 3 deletions scripts/create_build_adoc_doxygen.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))

Expand Down
34 changes: 17 additions & 17 deletions scripts/create_output_supplemental_data.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading