search

jothepro / doxygen-awesome-css

Custom CSS theme for doxygen html-documentation with lots of customization parameters.
https://jothepro.github.io/doxygen-awesome-css/
MIT License
981 stars 112 forks source link

Github Action to keep style up to date #65

Open tdegeus opened 2 years ago

tdegeus commented 2 years ago

I'm using the great style almost everywhere. I'm shipping this style simply with the library, because I don't like submodules. Keeping the style up-to-date is in issue however. We had a really nice contribution having a GH Action checking if the style is up-to-date, and if it is not it opens a PR by @1uc here https://github.com/BlueBrain/HighFive/pull/507 . It would be amazing if this would be converted in an 'official' GH Action !

gunvirranu commented 2 years ago

Just wanna mention that I'd use this! I thought about having my build system (CMake) pull down the latest version, but the extra complexity didn't seem worth it. I'm also not a fan of git submodules (especially if there's no others already), so automating the work to keep it up-to-date would be quite useful.

jothepro commented 2 years ago

If the most important aspect would be to eliminate the need to use submodules, maybe one could create a fork of https://github.com/marketplace/actions/doxygen-action that comes with a parameter to select a version of doxygen-awesome-css?

So one could then set up and run doxygen like so:

uses: jothepro/doxygen-action@v1.9.2
with:
    doxygen-awesome-css: v2.0.3

I'm just brainstorming, would that fit in your workflow?

jothepro commented 2 years ago

For users that want to take the risk of always being up-to-date one could then configure:

uses: jothepro/doxygen-action@v1.9.2
with:
    doxygen-awesome-css: latest
gunvirranu commented 2 years ago

Hey @jothepro, I appreciate the response! That's an interesting solution I hadn't thought of. I can definitely see why that would be useful, since it would lower the barrier to using this great theme even further.

Unfortunately, your proposal does mean that a local checkout can't build docs the same as CI would build them. Either the locally built docs use the default Doxygen theme, or it requires manually downloading a theme release, neither of which are ideal. Tbh, I don't expect anyone else but me to be building my projects' docs, but even ignoring that, I often build docs locally to confirm formatting changes.

Because of this, I don't think it would fit into my workflow specifically, but I'm just one person 🤷‍♀️. I'll think about this a bit further to see if I can come up with anything besides @tdegeus's original solution. Just off the bat though, the original idea does have the benefits of:

  1. Building docs locally without any additional steps, since a theme version is always checked into the repo
  2. Assisting with upgrading theme versions, because you can just checkout the auto-generated PR and do a local build before merging to check for issues
tdegeus commented 2 years ago

Thanks for the suggestion. Same here, I like to be able to build locally too. On top of that, I'm configuring with CMake, so I don't think that I can use the suggested action at all.