gh-libusb/hidapi
Watch
1
0
Fork
You've already forked hidapi
 0
Code Issues 58 Pull requests 18 Releases 13 Wiki Activity

Automate doxygen builds #521

Merged
2bndy5 merged 6 commits from automate-doxygen-builds into master 2023-04-05 04:41:15 -05:00
Conversation 20 Commits 6 Files changed 5 +562 -259
2bndy5 commented 2023-04-03 13:18:05 -05:00 (Migrated from github.com)

resolves #5

  • updated the doxyfile using doxygen -u
  • include hidtest/test.c as a doc'd example
  • use a brief doxygen/main_page.md file as the generated site's main page.
  • strip absolute paths from doxygen output (which now displays as relative paths to repo root)
  • added CI to build the docs and save as a CI artifact (useful for visual inspection without checking out a PR branch). This new CI will also rewrite the contents of the gh-pages branch for deployment (only for push events to the master branch).
  • added some missing docstrings and excluded undocumented "helper macros" to satisfy warnings output in doxygen's build log.

Admin prep

The required preparation needed from admins is

  1. make sure the repo's setting are set to use the gh-pages branch root folder as source of deployments.
    image
    I realize that there is already a branch named github_pages, but I think that branch was meant for a different purpose. The branch published to github pages typically only has the site's HTML resources (not any programming or documentation sources) -- especially when using Doxygen as the static site generator.
  2. make sure the custom domain is configured correctly. I mention this one because https://libusb.github.io/hidapi forwards to https://libusb.info/hidapi
  3. add the deployed site's link to the repo's "About" settings:
    image
    Alternatively (or additionally), a link could be added to the README in the "What does the API look like?" section.
resolves #5 - updated the doxyfile using `doxygen -u` - include hidtest/test.c as a doc'd example - use a brief `doxygen/main_page.md` file as the generated site's main page. - strip absolute paths from doxygen output (which now displays as relative paths to repo root) - added CI to build the docs and save as a CI artifact (useful for visual inspection without checking out a PR branch). This new CI will also rewrite the contents of the `gh-pages` branch for deployment (only for push events to the master branch). - added some missing docstrings and excluded undocumented "helper macros" to satisfy warnings output in doxygen's build log. ## Admin prep The required preparation needed from admins is 1. make sure the [repo's setting](https://github.com/libusb/hidapi/settings/pages) are set to use the `gh-pages` branch root folder as source of deployments. [![image](https://user-images.githubusercontent.com/14963867/229591707-79494dc6-7368-491b-8811-c3c46f7132ad.png)](https://docs.github.com/articles/configuring-a-publishing-source-for-github-pages/) I realize that there is already a branch named `github_pages`, but I think that branch was meant for a different purpose. The branch published to github pages typically only has the site's HTML resources (not any programming or documentation sources) -- especially when using Doxygen as the static site generator. 2. make sure the [custom domain](https://docs.github.com/articles/using-a-custom-domain-with-github-pages/) is configured correctly. I mention this one because https://libusb.github.io/hidapi forwards to https://libusb.info/hidapi 3. add the deployed site's link to the repo's "About" settings: ![image](https://user-images.githubusercontent.com/14963867/229592960-2e442cf4-b2aa-4596-b915-1eaaadef47bd.png) Alternatively (or additionally), a link could be added to the README in the ["What does the API look like?" section](https://github.com/libusb/hidapi#what-does-the-api-look-like).
Youw commented 2023-04-04 15:29:42 -05:00 (Migrated from github.com)

I've made a job on master branch, to test CI in this PR.
As for other changes/requests - I'll get to it tiny bit later. Too much preoccupied at the moment.

I've made a job on master branch, to test CI in this PR. As for other changes/requests - I'll get to it tiny bit later. Too much preoccupied at the moment.
2bndy5 commented 2023-04-04 15:54:48 -05:00 (Migrated from github.com)

I realize that there is already a branch named github_pages, but I think that branch was meant for a different purpose. The branch published to github pages typically only has the site's HTML resources (not any programming or documentation sources) -- especially when using Doxygen as the static site generator.

The branch used to publish the docs' site can be configured (see here) Default is a branch named gh-pages.

> I realize that there is already a branch named github_pages, but I think that branch was meant for a different purpose. The branch published to github pages typically only has the site's HTML resources (not any programming or documentation sources) -- especially when using Doxygen as the static site generator. The branch used to publish the docs' site can be configured ([see here](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-set-another-github-pages-branch-publish_branch)) Default is a branch named `gh-pages`.
Youw (Migrated from github.com) reviewed 2023-04-04 17:41:35 -05:00
doxygen/main_page.md
@ -0,0 +1,13 @@
# HIDAPI Doxygen output
Youw (Migrated from github.com) commented 2023-04-04 17:41:35 -05:00

update links

update links
Youw (Migrated from github.com) reviewed 2023-04-04 17:49:41 -05:00
Youw (Migrated from github.com) reviewed 2023-04-04 17:55:08 -05:00
hidapi/hidapi.h
@ -103,10 +105,11 @@
#ifdef __cplusplus
Youw (Migrated from github.com) commented 2023-04-04 17:55:07 -05:00

as per agreement - we use only /** c-style comments */ - for consisteny

as per agreement - we use only `/** c-style comments */` - for consisteny
Youw (Migrated from github.com) reviewed 2023-04-04 17:59:28 -05:00
Youw (Migrated from github.com) reviewed 2023-04-04 19:01:58 -05:00
.github/workflows/docs.yaml
@ -16,0 +54,4 @@
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
Youw (Migrated from github.com) commented 2023-04-04 19:01:57 -05:00

I don't think the history of documentation changes has any value in the branch, given that all doc sources are in the repo anyway

          publish_dir: ./docs
          force_orphan: true
I don't think the history of documentation changes has any value in the branch, given that all doc sources are in the repo anyway ```suggestion publish_dir: ./docs force_orphan: true ```
Youw commented 2023-04-04 19:03:48 -05:00 (Migrated from github.com)

already a branch named github_pages, but I think that branch was meant for a different purpose

originally it was created for the same purpose as a playground
we just didn't make it right to the end
at this moment I believe it is time to get rid of it

> already a branch named `github_pages`, but I think that branch was meant for a different purpose originally it was created for the same purpose as a playground we just didn't make it right to the end at this moment I believe it is time to get rid of it
Youw (Migrated from github.com) reviewed 2023-04-04 19:23:23 -05:00
.github/workflows/docs.yaml
@ -16,0 +43,4 @@
concurrency:
group: "github-pages-deploy"
cancel-in-progress: true
steps:
Youw (Migrated from github.com) commented 2023-04-04 19:23:22 -05:00

lets make sure to deploy only the latest

    concurrency:
      group: "github-pages-deploy"
      cancel-in-progress: true
    steps:
lets make sure to deploy only the latest ```suggestion concurrency: group: "github-pages-deploy" cancel-in-progress: true steps: ```
Youw commented 2023-04-04 19:28:19 -05:00 (Migrated from github.com)
image
<img width="1154" alt="image" src="https://user-images.githubusercontent.com/5939659/229951342-bca0fbad-3e57-4344-992f-78abbc34b214.png">
👍 1
2bndy5 (Migrated from github.com) reviewed 2023-04-04 20:00:30 -05:00
doxygen/main_page.md
@ -0,0 +1,13 @@
# HIDAPI Doxygen output
2bndy5 (Migrated from github.com) commented 2023-04-04 20:00:30 -05:00

Oops! 😆

Oops! 😆
2bndy5 (Migrated from github.com) reviewed 2023-04-04 20:02:41 -05:00
hidapi/hidapi.h
@ -103,10 +105,11 @@
#ifdef __cplusplus
2bndy5 (Migrated from github.com) commented 2023-04-04 20:02:41 -05:00

Oh, I couldn't find any code style guideline, but I didn't look very hard...

Oh, I couldn't find any code style guideline, but I didn't look very hard...
2bndy5 (Migrated from github.com) reviewed 2023-04-04 20:17:22 -05:00
hidapi/hidapi.h
@ -103,10 +105,11 @@
#ifdef __cplusplus
2bndy5 (Migrated from github.com) commented 2023-04-04 20:17:21 -05:00

done. The < is required as part of doxygen trailing docstring syntax.

done. The `<` is required as part of doxygen trailing docstring syntax.
2bndy5 (Migrated from github.com) reviewed 2023-04-04 20:20:08 -05:00
2bndy5 (Migrated from github.com) reviewed 2023-04-04 20:23:34 -05:00
2bndy5 (Migrated from github.com) reviewed 2023-04-04 21:00:12 -05:00
doxygen/Doxyfile
2bndy5 (Migrated from github.com) commented 2023-04-04 21:00:12 -05:00

This is the important part that allows eliding specific members from the generated docs. ✏️ Here, I used it to exclude the "helper macros" that don't have a docstring.

This is the important part that allows eliding specific members from the generated docs. ✏️ Here, I used it to exclude the "helper macros" that don't have a docstring.
Youw (Migrated from github.com) reviewed 2023-04-05 04:32:19 -05:00
hidapi/hidapi.h
@ -103,10 +105,11 @@
#ifdef __cplusplus
Youw (Migrated from github.com) commented 2023-04-05 04:32:18 -05:00

couldn't find any code style guideline

unfortunately those aren't written anywhere
just the fact of consistency

> couldn't find any code style guideline unfortunately those aren't written anywhere just the fact of consistency
Youw (Migrated from github.com) reviewed 2023-04-05 04:33:26 -05:00
Youw (Migrated from github.com) reviewed 2023-04-05 04:36:52 -05:00
doxygen/main_page.md
@ -0,0 +1,13 @@
# HIDAPI Doxygen output
This site is dedicated to hosting an [API reference for the HIDAPI library](#API).
Youw (Migrated from github.com) commented 2023-04-05 04:36:52 -05:00

I'm not sure where #API link points to

I'm not sure where `#API` link points to
Youw (Migrated from github.com) reviewed 2023-04-05 04:38:56 -05:00
doxygen/main_page.md
@ -0,0 +1,13 @@
# HIDAPI Doxygen output
This site is dedicated to hosting an [API reference for the HIDAPI library](#API).
Youw (Migrated from github.com) commented 2023-04-05 04:38:56 -05:00

ah, I see - that's a Doxygen link

ah, I see - that's a Doxygen link
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
3rdparty
3rd-party related issue/question

  
Android
Android OS related

  
API
API change, Version 1 stuff

  
Author does not respond

   
bsd
FreeBSD, NetBSD, OpenBSD, etc

  
bug
Something isn't working

  
build system/CI
Anything related to building the project or running on CI

  
ci-virtual-device
Run the virtual HID device CI jobs (Windows driver + libusb raw-gadget)

  
CMake
Related to CMake build system

  
Contributions Welcome
Any external help is welcome

  
Core
Related to common codes like hidapi.h

  
dependencies
Pull requests that update a dependency file

  
device-specific
Issues/PRs related to a specific device

  
documentation
Improvements or additions to documentation

  
don't_merge
Don't merge this PR as is

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
Example
Related to hidtest or new examples

  
Haiku
Related to Haiku OS (using libusb backend)

  
hidraw
Related to Linux/hidraw backend

  
hotplug
Related to hotplug

  
info required
Need more input from PR/issue author

  
invalid
Not a HIDAPI issue

  
libusb
Related to libusb backend

  
macOS
Related to macOS backend

  
Misc
Typo, whitespace, etc.

  
Not an issue

   
question
Information is requested

  
Release
Related to new release

  
Test
Related to built-in test (not hidtest)

  
Test GUI
Related to a Test GUI application

  
Windows
Related to Windows backend

  
wontfix
This will not be worked on

No labels
3rdparty
Android
API
Author does not respond
bsd
bug
build system/CI
ci-virtual-device
CMake
Contributions Welcome
Core
dependencies
device-specific
documentation
don't_merge
duplicate
enhancement
Example
Haiku
hidraw
hotplug
info required
invalid
libusb
macOS
Misc
Not an issue
question
Release
Test
Test GUI
Windows
wontfix
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
gh-libusb/hidapi!521
No description provided.