doxygen released 1.9.2

[梁永祥]

release: https://github.com/doxygen/doxygen/releases/tag/Release_1_9_2

So are we considering upgrading to the new version?

[Brendan]

I would appreciate a version option in this action.

I say this because doxygen v1.9.2 seems to have problems with outputting unmatched closing tags in the XML output. This prevents v1.9.2 working properly with the breathe extension for building sphinx docs from doxygen's parsers (via doxygen's XML output)

[Matt C]

Quite frankly, I'm not sure what the best way of handling this is. Alpine doesn't keep old packages in their repositories so we'd have to have different versions of the action for different versions of alpine which provide different versions of doxygen. Any input would be appreciated :)

[Brendan]

This may seem over-complicated, but it's an idea.

Use a customized docker image.

A while ago, I helped develop an action that needed all available releases of clang-tools. The docker image we use has them all installed (which saved a lot of setup time for each workflow run). This way, we just had to append the version to the executable invocation (ie clang-tidy10).

IDK if installing multiple versions of doxygen will allow using commands like doxygen-1.8.17, but I'm pretty sure Linux has a way to alias executables (like the way python2 vs python3 is done).

[Matt C]

I've tried that before actually, but pulling the image at the start of the workflow was always longer than the whole install process normally (even when you had LaTeX being installed too) :(

[Brendan]

If you're installing from source, then you have more options.

• CMake allows you to change the install destination (via CMAKE_INSTALL_PREFIX or something similar). This would only make sense if building multiple versions before using the action's input
• git checkout the tag specified and build/install doxygen from source. There would need to be error detection when the user specified an invalid tag. And, I'm not sure if the build process is consistent with older versions of doxygen (using CMake or an older configure script).

[Brendan]

If not installing from source or building from source requires extra dependencies, you could download the built binary for Linux x86-64 from sourceforge

[Brendan]

ok I did some testing with the suggestions I made:

1. Installing from src is a lengthy process (~3-4 minutes) and that was without installing any particuluar deps (ubuntu-latest seems to have most already installed - IDK about libiconv though).
2. Installing from bin archive fetched from SourceForge files requires libclang deps as the bin archives are "dynamically linked against libclang version 9". However, this was easily remedied with apt-get install libclang1-9 libclang-cpp9. Furthermore the install from bin archive took ~15-18 seconds (including the apt-get install).

Here's the solution I used to test in a GH workflow:

  build_docs:
    strategy:
      matrix:
        doxygen: ['1.9.1']

    runs-on: ubuntu-latest
    steps:
    - name: install graphviz and libclang deps
      run: sudo apt-get install graphviz libclang1-9 libclang-cpp9
    - name: install doxygen from SF binary archives
      run: |
        mkdir doxygen && cd doxygen
        curl -L https://sourceforge.net/projects/doxygen/files/rel-${{ matrix.doxygen }}/doxygen-${{ matrix.doxygen }}.linux.bin.tar.gz > doxygen.tar.gz
        gunzip doxygen.tar.gz
        tar xf doxygen.tar
        cd doxygen-${{ matrix.doxygen }}
        sudo make install

When testing this locally, I had to use sudo make -B install for some reason, but that isn't needed for the GH runner. Notice that I'm also installing graphviz, so removing that would likely reduce the run time for the sudo apt-get install libclang1-9 libclang-cpp9 necessity.

Lastly, I'm not sure what else might be needed to install doxygen from pre-built bin archives when using the Alpine docker img. Here's a note about the bin archives from the doxygen install instructions

Compiled using Ubuntu 20.04 and dynamically linked against libclang version 9. This archive includes the HTML version of the manual, and the GUI frontend compiled against Qt5.

Since I never called the doxygen GUI, I didn't need to make sure Qt5 was present.

ps - Very old versions of doxygen might actually have been linked to older versions of libclang (but libclang-9 is the oldest available via apt-get).

[Brendan]

It looks like only clang v10 is available in the Alpine's apk repos; I checked 3.13 & 3.12 on a mirror that was closest to me. ☹️

@mattnotmitt In the end, if you decide to upgrade this action to using v1.9.2, then I'll have to migrate away from using this action (using the solution I outlined with installing doxygen from bin archives) - clearly I'm ready now for when you do upgrade it.

[Matt C]

Hey @2bndy5 just noticed that doxygen 1.9.3 has been released - does this fix your issue? It's not in alpine yet so I wouldn't be moving the package along. Besides that, I've been considering a versioning this action based on the doxygen version so if you need 1.9.1 it's mattnotmitt/doxygen-action@1.9.1 - I'd keep moving v1 along with whatever the version on alpine's edge is.

[Brendan]

I just tested the project that used breathe + doxygen with v1.9.3, and I can confirm the problem is fixed (concerning unmatched XML tags).

Recently, I noticed another bug in the doxygen's HTML output (related to documenting python using the source browser feature) for 1.9.1 & 1.9.2 was fixed in 1.9.3 👍🏼

[Matt C]

Great to hear. Once alpine gets around to adding v1.9.3 to their edge I'll tag that version for the repo. For the time being you should be able to use the locked version of 1.9.1 I mentioned above :)

[梁永祥]

Great. I'll try to use it later.