Skip to content

Add script to extract CMake function descriptions #2422

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

Jump to bottom
Merged
merged 19 commits into from
Apr 29, 2025
Merged

Add script to extract CMake function descriptions #2422

merged 19 commits into from
Apr 29, 2025

Conversation

will-v-pi
Copy link
Contributor

This adds a script to extract CMake functions and output them as a TSV file, similar to extract_cmake_configs.py for PICO_CMAKE_CONFIG variables

Also adds basic descriptions for all functions missing them, other than some which are set as allowed to be missing them in the script

@will-v-pi will-v-pi added this to the 2.1.2 milestone Apr 14, 2025
@will-v-pi will-v-pi requested a review from kilograham April 14, 2025 15:47
@will-v-pi will-v-pi force-pushed the extract-cmake-functions branch 2 times, most recently from 2b4a2d0 to b9dd179 Compare April 14, 2025 17:10
lurch
lurch reviewed Apr 14, 2025
View reviewed changes
lurch
lurch reviewed Apr 14, 2025
View reviewed changes
@lurch
Copy link
Contributor

lurch commented Apr 14, 2025 •
edited
Loading

Looks like 79b3eb2 probably shouldn't be in this PR?

EDIT: Discussed offline. Reasons. 😉

@will-v-pi will-v-pi force-pushed the extract-cmake-functions branch from b9dd179 to 42388f6 Compare April 15, 2025 08:31
@will-v-pi
Copy link
Contributor Author

(Rebased onto #2423 for now, will rebase onto develop once that's merged)

lurch
lurch reviewed Apr 15, 2025
View reviewed changes
@will-v-pi will-v-pi force-pushed the extract-cmake-functions branch from 1a4906c to 171daf7 Compare April 15, 2025 15:29
kilograham
kilograham reviewed Apr 16, 2025
View reviewed changes
@kilograham
Copy link
Contributor

would be good to see some sample PDF output for these... i wonder if there is a simple way we can deal with parameters... maybe treating any line which starts with a capitilized "SOME_VAR description" as a parameter

lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
lurch
lurch reviewed Apr 23, 2025
View reviewed changes
@kilograham kilograham self-assigned this Apr 23, 2025
@lurch
Copy link
Contributor

lurch commented Apr 24, 2025 •
edited
Loading

Looking at the latest TSV file that this generates, each row is indeed now a single line ( 💯 ), but there seems to be multiple \n\n at the start and end of each description, which seems a bit superfluous?

EDIT: Which you could probably fix with something like:

desc = re.sub(r'^(?:\\\\n)*(.+?)(?:\\\\n)*$', r'\1', desc)

lurch
lurch reviewed Apr 24, 2025
View reviewed changes
@lurch
Copy link
Contributor

lurch commented Apr 24, 2025

IMHO the extracted TSV file is looking much better now, thanks 👍 (If you've not already seen it, there's a really nice "Rainbow CSV" extension for VSCode which gives the different columns different colours, which is pretty handy!)

But the descriptions still have things like:

... included)\n\nDEFAULT_ALARM_POOL    - default alarm pool setup;\nPRINTF                - full printf ...

so perhaps it's worth doing desc = re.sub(' +', ' ', desc) too?

lurch
lurch reviewed Apr 26, 2025
View reviewed changes
@lurch lurch mentioned this pull request Apr 26, 2025
Merged
@will-v-pi
Copy link
Contributor Author

IMHO the extracted TSV file is looking much better now, thanks 👍 (If you've not already seen it, there's a really nice "Rainbow CSV" extension for VSCode which gives the different columns different colours, which is pretty handy!)

But the descriptions still have things like:

... included)\n\nDEFAULT_ALARM_POOL    - default alarm pool setup;\nPRINTF                - full printf ...

so perhaps it's worth doing desc = re.sub(' +', ' ', desc) too?

I think it's better to leave those spaces in, as they align the - for each line if you do print them out in full, or they can just be compressed to one space by downstream tooling

will-v-pi added 16 commits April 28, 2025 11:36
@will-v-pi
Handle newlines elsewhere - just remove #
a185344 
Also print warnings for functions missing descriptions
@will-v-pi
Add descriptions for all functions missing them
bce438b
@will-v-pi
Tidy up some descriptions
370b5c8
@will-v-pi
Fixup description and logging
c39d969
@will-v-pi
Add commas to pico_btstack_make_gatt_header description
43f482e
@will-v-pi
Fix boot_stage2 function arguments
a8fca57 
They don't take a TARGET argument
@will-v-pi
Specify commands set target properties
cfb3895
@will-v-pi
Add support for including commands in the cmake function descriptions
36f154b 
brief - a brief description

brief_nodesc - a brief description, which should be excluded from the full description

param - a parameter and it's description
@will-v-pi
Review fixups
920859c 
Detail unsupported characters

ret -> desc

Add some manual sorting of tools/cmake functions

Use dicts for all_functions items
@will-v-pi
Remove # from description
e796aeb
@will-v-pi
Add checking for duplicate functions with different definitions
e5ae814
@will-v-pi
Remove unused name
b840bc8
@will-v-pi
Remove newlines at start/end of description, and tidyup splitting com…
582b9ee 
…mands
@will-v-pi
Fix signature parameter checking
9f0a42c
@will-v-pi
Add commas to pico_set_lwip_httpd_content description
5339325
@will-v-pi
Add groups names and descriptions
e4b7b7c 
Adds entries to the TSV beginning with `_desc_` for the group name (in the brief column) and description
@will-v-pi will-v-pi force-pushed the extract-cmake-functions branch from ed17d8e to e4b7b7c Compare April 28, 2025 10:36
lurch
lurch previously approved these changes Apr 28, 2025
View reviewed changes
lurch
lurch reviewed Apr 28, 2025
View reviewed changes
lurch
lurch reviewed Apr 28, 2025
View reviewed changes
@lurch lurch mentioned this pull request Apr 28, 2025
Open
kilograham
kilograham reviewed Apr 29, 2025
View reviewed changes
tools/extract_cmake_functions.py

# Group descriptions
group_names_descriptions = {
'boot_stage2': ('Boot Stage 2', 'CMake functions to create stage 2 bootloaders'),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had thought to add these in the CMake files themselves, but this is certainly fine for now

@kilograham kilograham merged commit 6e31579 into develop Apr 29, 2025
8 checks passed
@kilograham kilograham deleted the extract-cmake-functions branch April 29, 2025 16:09
@kilograham
Copy link
Contributor

  • I will add some more docs as a separate PR
  • @will-v-pi it would be nice to (perhaps manually) tag the functions as rp2040 or rp2350 in the SDK book

@hanshuebner hanshuebner mentioned this pull request May 18, 2025
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kilograham kilograham kilograham left review comments

@lurch lurch lurch approved these changes

Assignees

@kilograham kilograham

Labels
None yet
Projects
None yet
Milestone
2.1.2
Development

Successfully merging this pull request may close these issues.
3 participants
@will-v-pi @lurch @kilograham