Add documentation CI/CD workflow and update Doxygen CSS theme

[glopesdev]

Documentation will automatically publish to GitHub Pages when:

• A release is made
• A manual workflow dispatch is initiated and publishing is enabled
• Any push to any branch is made when CONTINUOUS_DOCUMENTATION is enabled (intended for use in forks for development purposes, but this is not enforced.)

---

Doxygen was also updated to version 1.12.0, the layout updated to use Doxygen Awesome CSS theme, and favicon and logo added for consistency with other Harp documentation websites.

Following merge to main the new layout will be published.

Preview at: https://glopesdev.github.io/core.pico/

[PathogenDavid]

Left some other last-minute thoughts on Doxygen stuff and things. No show-stoppers, mainly polish stuff.

[PathogenDavid]

It would be really nice if clicking this or the project name brought you back to the main page like most websites do.

[glopesdev]

Good point, I wonder if it would be more or less confusing to have the logo point to harp-tech.org instead of the main page?

I say this since there is already a link to the index of the Core Pico in the navigation bar called "Main Page" which would then become redundant. I wonder if there is a way to reorganize that, but I couldn't find it.

[Poofjunior]

Thanks for taking a pass at cleaning up the presentation! I confirmed that I can generate the documentation locally. (Dark mode looks great too!)

Do have thoughts on where self-contained examples could go within the documentation? (For small, in-line examples demonstrating the use of a function, we can put them inside the function with \code and \endcode.)

(Aside: this is probably a good incentive for me to clean up the interface and hide some of the extraneous functions as private so

When the docs go live, let's make sure that we link the final docs link in the main README (or somewhere else that's easy to find.)

[Poofjunior]

Another observation from my end: is it possible to sort public and private member functions into separate categories?

What I'm seeing now is one huge alphebatized list where membership is flagged with a tag. I think the tags are useful, but what might be more helpful is to just bunch all of the private member functions together at the end. Most users wont need to reference these, so they just kinda get in the way.

(I'm trying to put myself in the shoes of a totally new user that wants to get a sense of what they can do with the Harp core at a glance.)

[glopesdev]

Most users wont need to reference these, so they just kinda get in the way.

@Poofjunior that sounds reasonable, I will look it up, but in case this is not possible, what about just hiding all private functions?

In case a developer needs to access implementation details I would imagine they can always just look directly at the files or source code.

P.S.: it looks like one way to achieve this if we really wanted to show private members would be by explicitly grouping them by member groups but they need to be manually curated in the source code.

[Poofjunior]

@Poofjunior that sounds reasonable, I will look it up, but in case this is not possible, what about just hiding all private functions?

In case a developer needs to access implementation details I would imagine they can always just look directly at the files or source code.

P.S.: it looks like one way to achieve this if we really wanted to show private members would be by explicitly grouping them by member groups but they need to be manually curated in the source code.

@glopesdev Ideally we find a way to separate them in the docs, but in a pinch, hiding all the private member functions seems totally ok too.

[glopesdev]

What I'm seeing now is one huge alphebatized list where membership is flagged with a tag.

@Poofjunior Can you send a link to an example where you see this?

• In the Class Members index I do see an alphabetical ordering: https://glopesdev.github.io/core.pico/functions.html
• However inside the class reference the members do seem to be grouped by access modifier, from public to private (group links at the top): https://glopesdev.github.io/core.pico/classHarpCore.html

Let me know if this grouping is enough, otherwise I might remove private members for now while we figure out a different strategy.

I have experimented using @defgroup and that works too, but the groups would need to be manually curated, and would be placed inside the Topics index category as what happens now for pico_stdio_usb.

[glopesdev]

Do have thoughts on where self-contained examples could go within the documentation? (For small, in-line examples demonstrating the use of a function, we can put them inside the function with \code and \endcode.)

Not many thoughts, as I have no prior experience with Doxygen and also not sure yet who will be maintaining these docs or writing the examples. Probably would be easier to discuss that first and go into more detail through the examples themselves, to get a feeling of how extensive they might be, etc. outside of this PR.

I am documenting below some of my ramblings on a brief exploration I did with Doxygen for future reference.

Doxygen allows for different grouping strategies usually built around the concept of a topic group, but we can also use Subpaging to make structure a bit more natural for the person who is editing the documentation.

For example we could have something like:

📦docs
 ┣ 📂articles
 ┃ ┣ 📂examples
 ┃ ┃ ┣ 📜blinking.md
 ┃ ┃ ┗ 📜irq.md
 ┃ ┗ 📜examples-toc.md
 ┣ 📜Doxyfile
 ┗ 📜README.md

examples-toc.md

\page examples Examples
- \subpage blinking
- \subpage irq

blinking.md

\page blinking Blinking
# Blinking

Description of the blinking example.

This generates the below hierarchical structure in the index, with a separate navigation bar entry for "Related pages".

This may or may not be interesting as it creates yet another documentation section. Alternatively we could just keep to "Topics" and define subgroups, but I haven't been able to get them to create nested hierarchies properly.

[Poofjunior]

@glopesdev another documentation section is totally acceptable. I think this would be a great draft, and I agree that we can probably discuss example placement/content later.

[Poofjunior]

@glopesdev feel free to delete the branch at your leisure!

[glopesdev]

@Poofjunior thanks for merging, actually I had forgotten to push two more changes to address your comments above, but I will open a separate PR for that.

[Poofjunior]

@glopesdev got it and thank you! I just merged that one too. Cheers!