[Request] Doxygen automated upload to tmrh20.github.io

[2bndy5]

@Avamander and I briefly discussed this issue but fell short of a final resolution without @TMRh20's involvement. Currently doc changes are built locally then uploaded to the appropriate subdirectory of hosting repo. I've devised a workflow that fetches the latest release version number (pre-releases and drafts ignored), then builds the doxygen "html" outputted folder in this repo's "docs" folder. Notice the .gitignore file excludes comiting changes to the "docs" folder (& now also a doxygenAction file -- I'll explain that file in a second). Meaning this workflow does not make any (meaningful) alterations to the 'doxygenfile'. Except, I added a comment to the 'doxygenfile' on the last line showing how the workflow uses it (mostly for local testing -- thus the new addition to .gitignore), but I can remove it.

# @INCLUDE = doxygenAction

In the workflow, I used bash commands to generate a file called doxygenAction and then add the un-commented version of the line above to the doxygenfile. This overrides (only during the workflow) the PROJECT_NUMBER (fetched using a separate action) & OUTPUT_DIRECTORY tags in the doxygenfile. Thus, we now have a github workflow that builds the docs using doxygen which can notify us of any build errors.

Here is the github action's workflow file. Notice the commented-out final step that I used (on a un-related separate personal repo) to make use of github-pages deployment.

Here are the workflow results.

Where to go from here?

In the link at the top of this post @Avamander suggested the use of git submodules on the hosted repo. My idea is to host this repo's docs under a gh-pages branch and have the tmrh20.github.io's main page link to this repo's github-pages deployment. Either way will require @TMRh20's approval and involvement.

I'm still open other ideas/alternatives.

p.s. About the PROJECT_NUMBER tag: I'd like to use the latest commit's sha reference (last 6 alphanumeric characters) to append a "patch version" to the latest stable release, but currently the workflow only uses the latest stable release version.

[Avamander]

suggested the use of git submodules on the hosted repo.

For any (theme) dependencies, yes, the actual location where the output is served from is configurable. A Doxygen theme is a good idea if you wish things would look a bit nicer.

[Avamander]

My idea is to host this repo's docs under a gh-pages branch and have the tmrh20.github.io's main page link to this repo's github-pages deployment.

That would work. It would be nice to have a redirect under TMRh20's repos, but it's not mandatory. All the "official" references can be updated.

[2bndy5]

This issue (about deployment using gh-pages) has to wait until this repo gets "unpaused". My idea for deployment does work, but the gh-pages branch needs to be created and then fail if using github token (most common practice). More details about the commented-out action can be found here (see the readme's "Tips and FAQ" section).

[2bndy5]

I noticed the installation instruction reference RF24 & RF24Network for this repo. Don't want to open another issue yet (belongs on RF24Network repo when this gets closer to resolution), so the RF24Network library docs' link to build instructions may need to be adjusted depending how this issue gets resolved (if at all).

[Avamander]

Reading the thing again, I think the github.io pages of the repos or the org should be used instead. Makes it a bit nicer and easier.

[2bndy5]

yep, but this issue would need to be addressed for every repo in the org (Copy, Paste, Rinse, and Repeat).

Thanks for re-reading, I do put some time and effort into my posts (contrary to what it may seem). BTW, I was an english tutor (prior to the pandemic), so there's that too.

[Avamander]

yep, but this issue would need to be addressed for every repo in the org (Copy, Paste, Rinse, and Repeat).

Yes, but that makes sense with different pieces of code having separate documentation.

[2bndy5]

I'm not sure, but I think we can cross reference documentation between repos directly with doxygen's TAGFILES option in the doxyfile. Though this may be only useful for the other repos that use RF24 as a core dependency. I'm finding it difficult to understand doxygen's "manual"...

[2bndy5]

I've been testing a deploy of my fork's docs to my fork's gh-pages branch. It seems that the main page has some hardcoded links to tmrh20.github.io/RF24 directory

[2bndy5]

@Avamander @TMRh20 can you enable github pages deployment to the new gh-pages branch? I expect this first deployment to fail, render a blank page, or 404 error. I have configured the Doxygen build action to only update the gh-pages deployment on release events; otherwise it just build the docs to make sure they can be built on push/PR events.

Also this repo's settings should have an ability to hide the "packages" & "environments" on the side bar. The "packages" section will never apply since the only package manager that this library uses is the Arduino Library Manager. The "environments" section will be superfluous once we change the doc links in the README to this repo's gh-pages deployment (though I have no complaints if this section is left visible).

[Avamander]

@2bndy5 I enabled it, but do you want to place the docs in / or /docs?

[2bndy5]

no need. the workflow works fine without it. Also having a blank docs folder would require an exception to gitignore and a .gitkeep file within the folder... it works as is.

@Avamander If your curious how this will look, you can see the gh-pages branch on my fork as well as the latest deployment from publishing a release from my fork

[2bndy5]

I noticed the datasheets are hosted at tmrh20.github.io repo. I'm ok with keeping it this way, but I think they would be more accessible to host the datasheets on nRF24/RF24 repo.

While I'm thinking of it, I can also add (to the RF24 repo) datasheets for the Si24R1 (only available in chinese) and whatever other clones are targeted for "official" support. This would help provide a reference point for every time @Avamander or @TMRh20 asks about supported clones/counterfeits when I (or someone else) propose a change to the library. BTW I found a half-baked repo/library that also hosts many of the datasheets for nRF24L01 clones/counterfeits

[TMRh20]

they would be more accessible to host the datasheets on nRF24/RF24 repo.

I'm ok with putting the datasheets wherever the documentation is at.

While I'm thinking of it, I can also add (to the RF24 repo) datasheets for the Si24R1 (only available in chinese) and whatever other clones are targeted for "official" support.

I don't want to say we "officially" support the clones, its been more of 'I don't know what is going on with all these devices, and making a few small changes makes the issues go away' lol. Over time we've learned more or less that some of these devices are pretty obscure, but many people still have them, so keeping a few lines of code and/or documentation in place prevents issues from coming up repeatedly.

With that, I'm content with just having the main nrf24l01 datasheets hosted here, I don't think its necessary to add all the others, unless maybe a spot somewhere with the documentation, but again, then we have to maintain it...

[2bndy5]

I don't want to say we "officially" support the clones, its been more of 'I don't know what is going on with all these devices, and making a few small changes makes the issues go away' lol

I had a feeling that's how it goes which why I used quotes around "official" 😄

I'll add the genuine datasheets to my fork under a "./datasheets" folder. This will make all hard-coded links to href="http://tmh20.github.io/RF24" easier to replace (using ctrl+shift+h) with href="http://nRF24.github.io/RF24"

BTW, that repo I linked to has some interesting R&D info in the README about properly using the clones in comparison to the OG

[2bndy5]

@Avamander I've been giving it more thought, and the gh-pages deployment section on the side bar could be used to reference docs for older releases. However, the gh-pages deployments can only go back as far as v1.3.10 (or whatever the next release version will be). So, it might be useful to expose the gh-pages environment in the repo's sidebar after releasing whatever version comes after the next release (just some food for thought). word bubble in pic should've said tagged commits, but notice the tag is not shown

[Avamander]

So, it might be useful to expose the gh-pages environment in the repo's sidebar after releasing whatever version comes after the next release (just some food for thought).

Can you please rephrase this, what do you want to make available?

[2bndy5]

It wouldn't be too important right now, but chronologically

• gh-pages env not currently exposed in repo's side bar
• release v1.3.10 (first & only gh-pages deployment)
• release v1.3.11 (or whatever it will be tagged) and expose (un-hide) the gh-pages env in side bar so people can look at docs for v1.3.10 if needed

[2bndy5]

Sorry, disregard that last idea. Turns out the "View Deployment" buttons (seen in picture above) all link to latest deployment and have nothing to do with different versions.🤬

@Avamander I'm sorry. The gh-pages env on the repo's side bar should stay hidden forever. ☹️

[2bndy5]

Before next release I'd like to apply this issue's solution to the other RF24* libraries, and then we can change the links in index.html on tmrh20.github.io repo to point to the docs hosted by the individual repos.

Would it be ok if a change the OUTPUT_DIRECTORY to "/docs" instead of the "../../ArduinoBuilds/RF24 Docs" directory? Currently the workflow does not handle relative paths that extend beyond the parent directory of the working folder (even doxygen needs the directory to already be created before generating the html files).

[TMRh20]

Yup

On Nov 27, 2020, at 10:55 PM, Brendan notifications@github.com wrote:

 Before next release I'd like to apply this issue's solution to the other RF24* libraries, and then we can change the links in index.html on tmrh20.github.io repo to point to the docs hosted by the individual repos.

Would it be ok if a change the OUTPUT_DIRECTORY to "/docs" instead of the "../../ArduinoBuilds/RF24 Docs" directory? Currently the workflow does not handle relative paths that extend beyond the parent directory of the working folder (even doxygen needs the directory to already be created before generating the html files).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.