HIDAPI web site

LudovicRousseau commented

2019-06-05 05:04:49 -05:00

(Migrated from github.com)

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)

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 commented

2019-06-09 04:09:13 -05:00

(Migrated from github.com)

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.

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 commented

2019-09-30 16:40:39 -05:00

(Migrated from github.com)

@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 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 commented

2019-10-01 02:07:06 -05:00

(Migrated from github.com)

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 ?

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 commented

2019-10-02 12:44:23 -05:00

(Migrated from github.com)

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?

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 commented

2019-10-03 11:34:25 -05:00

(Migrated from github.com)

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.

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 commented

2019-10-08 16:50:25 -05:00

(Migrated from github.com)

@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 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 commented

2019-10-21 13:09:48 -05:00

(Migrated from github.com)

@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?

@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 commented

2019-10-21 14:21:56 -05:00

(Migrated from github.com)

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.

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 commented

2019-10-21 14:43:39 -05:00

(Migrated from github.com)

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

Youw commented

2019-10-21 15:38:32 -05:00

(Migrated from github.com)

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.)

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 commented

2019-10-22 03:13:31 -05:00

(Migrated from github.com)

@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.

@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 commented

2019-12-13 21:35:00 -06:00

(Migrated from github.com)

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

LudovicRousseau commented

2019-12-14 04:59:48 -06:00

(Migrated from github.com)

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

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 commented

2021-06-13 06:59:34 -05:00

(Migrated from github.com)

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

mcuee commented

2021-06-13 07:03:08 -05:00

(Migrated from github.com)

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

mcuee commented

2022-04-25 00:20:41 -05:00

(Migrated from github.com)

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

Youw commented

2023-03-12 08:57:29 -05:00

(Migrated from github.com)

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

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](https://github.com/libusb/hidapi/blob/master/README.md). I say that [README](https://github.com/libusb/hidapi/blob/master/README.md) + [Wiki](https://github.com/libusb/hidapi/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

👍 1

2bndy5 commented

2023-04-03 10:14:40 -05:00

(Migrated from github.com)

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

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).
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.
  github.com/libusb/hidapi@bd6be4d83b/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.

> 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. ![image](https://user-images.githubusercontent.com/14963867/229552350-d641fe3e-024b-49e5-8e82-4cea48c4259b.png) 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 commented

2023-04-03 10:58:09 -05:00

(Migrated from github.com)

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.

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 commented

2023-04-03 10:58:55 -05:00

(Migrated from github.com)

@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 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 commented

2023-04-03 11:59:52 -05:00

(Migrated from github.com)

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.

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 commented

2023-04-03 12:06:12 -05:00

(Migrated from github.com)

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...

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 commented

2023-04-05 04:52:26 -05:00

(Migrated from github.com)

#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?

#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: ```yaml # 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?

Rows
Columns

HIDAPI web site #5

Required tasks