HIDAPI web site

[LudovicRousseau]

Someone should work on a web site presenting the hidapi project and subprojects (like Python wrapper). goals:

• make the new hidapi project more visible so that it is indexed by search engine
• document the history from https://github.com/signal11/hidapi

One technical solution is to use github pages https://pages.github.com/ and host the web site at https://hidapi.libusb.info/ (the name does not exist yet but I can create it)

[z3ntu]

I've opened #16 to make the library documentation build again.

As http://signal11.us/ is down for some time, this should be prioritized - at least so the hidapi documentation is accessible again.

[Qbicz]

@LudovicRousseau could you please create the subdomain hidapi.libusb.info? I'm going to work to make the documentation live again.

I think it would be reasonable to create a subpage of hidapi with brief description, which will keep the style of libusb.info. From that page, we will link to doxygen docs.

[LudovicRousseau]

I can create the subdomain hidapi.libusb.info. How do you want me to configure it? Where do you want to host the web site?

Do you want to host the web pages at github as is the case for libusb with https://github.com/libusb/libusb.github.com ?

[Qbicz]

I think we are going to host the subdomain at github pages. I have some initial version here: https://qbicz.github.io/hidapi/group__API.html (I need to add overview page similar to libusb.info, right now it's API description only).

We can keep the website as a separate repo (just like libusb project does) or in docs/ directory.

How do you want me to configure it?

What information do you need?

[LudovicRousseau]

I created the project https://github.com/libusb/hidapi.github.io/ The (empty) web site is available at http://libusb.info/hidapi.github.io/

I am not sure it is possible to have http://hidapi.libusb.info/ to be redirected to http://libusb.info/hidapi.github.io/ using the DNS. A CNAME record will not work.

Maybe it is better to host the website in the /docs folder of https://github.com/libusb/hidapi The URL would then be https://libusb.info/hidapi and no need to update the DNS.

[LudovicRousseau]

@Qbicz any comment? The only available options for github pages are:

• master branch
• None

I guess you also have access to the 'Settings' of the hidapi project. You should be admin of the project/

I see the project has a github_pages branch. Maybe the branch should be called gh-pages or the HTML pages should be stored in /docs in the master branch as documented in https://help.github.com/en/articles/configuring-a-publishing-source-for-your-github-pages-site

[Qbicz]

@LudovicRousseau I think having address https://libusb.info/hidapi is fine. I also support idea of having the page on master branch in /docs.

Now I see you have tried a CNAME pointing to the hidapi.libusb.info and that it didn't work. Do you have idea why?

[Qbicz]

After a few trial & error, I would suggest having a simple website like this: https://qbicz.github.io/hidapi/

The layout is the Github Pages Jekyll theme "Minimal" and the content is generated from README.md of github project. What I want is link to https://qbicz.github.io/hidapi/group__API.html somewhere high on this page so the doc is easily accessible.

I also need to sort out doxygen directory layout, because it will not work currently if the doxygen html output is not in the main webpage directory.

[Qbicz]

Now the doxygen pages work like they should and the front page looks reasonable. What do you think @Youw @z3ntu @todbot?

[Youw]

https://qbicz.github.io/hidapi/ looks fine to me. Way better than nothing. Will we be able to replace it later with some separate page (without modifying a README)? (README is great but not really intended to be a real website home page.)

[LudovicRousseau]

@Qbicz you can't use a CNAME to redirect from http://hidapi.libusb.info/ to http://libusb.info/hidapi.github.io/. You can only redirect from one hostname to another hostname. You can't add anything to the URL.

You should be admin of the hidapi project. You have everything needed to enable github pages by yourself. It not just tell me.

[mcuee]

https://qbicz.github.io/hidapi/ redirects to https://hidapi.libusb.info/ and not reachable.

[LudovicRousseau]

I was expecting @Qbicz to enable github pages for this project. He/she should have all access rights needed. But still nothing was done.

[mcuee]

https://qbicz.github.io/hidapi/ is okay now.

[mcuee]

https://hidapi.libusb.info/ is not reachable though.

[mcuee]

https://qbicz.github.io/hidapi/ becomes outdated.

[Youw]

I don't see volunteers or any actual work regarding having a HIDAPI website. Even https://qbicz.github.io/hidapi/ - it is just a copy of the README.

I say that README + Wiki page is more than enough for documentary purposes.

As for (automatic) Doxygen generation and release on some web page - let's reopen this/get back to it, when someone will be willing to actually make it done.

Related: #357

[2bndy5]

As for (automatic) Doxygen generation and release on some web page - let's reopen this/get back to it, when someone will be willing to actually make it done.

I can do this so easily for you. I think it is important to have a site that outlines the actual API because different people have different learning abilities. Personally, learning by example, namely the terse script in the README, isn't one of my strengths.

Required tasks

• [x] fix Doxyfile to strip paths to sources properly. Currently the full path to hidapi.h is used in Doxygen's output when it should be just a relative path to repo root.
• [ ] admin needs to set github pages setting in this repo's settings to use the gh-pages branch. Not sure if this is done already. There was some discussion about using a CNAME (which is outside my expertise).
• [x] have the CI build and update the gh-pages branch on every push to master branch. This could also be limited to only happen when publishing a release.
• [ ] ~use the README as a Doxygen main page. All other .md files can be included as well, but they would go in a separate tab (usually named "Related Pages" but that can be customized).~
  • Note, using relative URLs (relative to github repo's path) in the md files does not work with Doxygen's rendered output. So, expect certain links to be broken in the rendered md pages from Doxygen. https://github.com/libusb/hidapi/blob/bd6be4d83b36d0dcd5401fb335384586b066a2eb/BUILD.md#L90-L95 The above links will not work when viewing the BUILD.md doc from Doxygen's output.

I know there's a way to create PDFs from Doxygen's latex output, but this seems like a secondary goal. I'm not well versed in creating a PDF from Doxygen's output though.

[Youw]

Volunteers are always welcome. If any specific admin/configuration assistance is needed on libusb or hidapi side - ask here. I'll either help myself or (if unable) will find someone who can.

[2bndy5]

@Youw I need feedback on this:

use the README as a Doxygen main page. All other .md files can be included as well, but they would go in a separate tab (usually named "Related Pages" but that can be customized).

Would you like to continue only using github to host the BUILD.*.md pages? If you want to host them with Doxygen as well, then it would take a lot more work to fix the linked URLs.

[Youw]

We can start not duplicating the same documentation on both Github and Doxygen. I love current approach with .md on Github because it is simple and I'm well familiar with the syntax, etc. If we eventually come up with something else (e.g. a tiny README on github and everything else moved to Doxygen/HIDAPI website) - I'm fine with it a long run. Whatever makes better sense in the end.

[2bndy5]

Thanks. I'll leave the md files as is. I've put together a special md file that would only get used as the Doxygen-rendered "Main Page" (which links back to the repo and the BUILD.*.md files). I've also added the hidtest/test.c module as a documented example; each documented API member used in the test.c will automatically be cross-linked to the member's doc info 🤓 .

PR inbound shortly...

[Youw]

#521 is briliant, thanks I've noticed interesting behavior: once we update the gh-pages with updated documentation - a special job is started, e.g.: https://github.com/libusb/hidapi/actions/runs/4617127465, which actually deploys the content of the branch elsewhere.

And it uses: https://github.com/actions/deploy-pages

Also, I've found another sample:

# Sample workflow for building and deploying a Jekyll site to GitHub Pages
name: Deploy Jekyll with GitHub Pages dependencies preinstalled

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["master"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

@2bndy5 how about we try to use actions/deploy-pages@v2 instead of peaceiris/actions-gh-pages@v3 and avoid the branch completely?