# Doxygen with Github Actions and Pages.

**URL:** https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790
**Category:** Engineering
**Tags:** doxygen
**Created:** [February 7, 2022, 8:48pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790 "2022-02-07T20:48:48Z")
**Posts on this page:** 20
**Page:** 1

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [February 7, 2022, 8:48pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/1 "2022-02-07T20:48:48Z")

</div>

I recently made some [changes](https://github.com/InsightSoftwareConsortium/ITK/pull/3030) with the ITK Doxygen configuration to minimize the about of changes from night to night in the HTML generated by Doxygen. Minimizing the number of files modified each day enabled regular web caching based on modified time to work, and adds with small daily updated to a git hub pages branch.

I have created a GitHub repository here: [https://github.com/blowekamp/ITKDoxygen](https://github.com/blowekamp/ITKDoxygen) with associated gh-pages here: [https://github.com/blowekamp/ITKDoxygen/deployments/activity\_log?environment=github-pages](https://github.com/blowekamp/ITKDoxygen/deployments/activity_log?environment=github-pages)

It also uses a described docker container, a steps so that anyone can easily regenerate and debug the Doxygen generation process. The GitHub Actions has been successfully updating the gh-pages for over a month now. Unfortunately, the searching does not work currently but there are likely options for Doxygen that should enable the functionality.

I’m not sure if there is any wider interest in using this infrastructure for main ITK Doxygen generation. Please let me know.

Also there is some specialized javascript code for advanced caching that may no longer be needed with the removal of daily modification of HTML file.

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [February 7, 2022, 9:06pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/2 "2022-02-07T21:06:48Z")

</div>

These changes sound useful. @matt.mccormick @kitware-sysadmin might be able to help.

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [February 11, 2022, 1:54pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/3 "2022-02-11T13:54:59Z")

</div>

I recently merged a PR do fix some issues the itkgroup.pl doxygen processing file:

> <https://github.com/InsightSoftwareConsortium/ITK/pull/3183>
>
> Fix many methods being documented in Doxygen with wrong strings.
> The the proces…ses performed in the itkgroup.pl is fixed to produce the
> proper indents for the modified auto-groupings.
> 
> Co-authored-by: Dave Chen \<dchen@mail.nih.gov\>
> 
> \<!-- The text within this markup is a comment, and is intended to provide
> guidelines to open a Pull Request for the ITK repository. This text will not
> be part of the Pull Request. --\>
> 
> 
> \<!-- See the CONTRIBUTING (CONTRIBUTING.md) guide. Specifically:
> 
> Start ITK commit messages with a standard prefix (and a space):
> 
> \* BUG: fix for runtime crash or incorrect result
> \* COMP: compiler error or warning fix
> \* DOC: documentation change
> \* ENH: new functionality
> \* PERF: performance improvement
> \* STYLE: no logic impact (indentation, comments)
> \* WIP: Work In Progress not ready for merge
> 
> Provide a short, meaningful message that describes the change you made.
> 
> When the PR is based on a single commit, the commit message is usually left as
> the PR message.
> 
> A reference to a related issue or pull request (https://help.github.com/articles/basic-writing-and-formatting-syntax/#referencing-issues-and-pull-requests)
> in your repository. You can automatically
> close a related issues using keywords (https://help.github.com/articles/closing-issues-using-keywords/)
> 
> @mentions (https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-people-and-teams)
> of the person or team responsible for reviewing proposed changes. --\>
> 
> \## PR Checklist
> \- \[\] No \[API changes\](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md#breaking-changes) were made (or the changes have been approved)
> \- \[\] No \[major design changes\](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md#design-changes) were made (or the changes have been approved)
> \- \[\] Added test (or behavior not changed)
> \- \[\] Updated API documentation (or API not changed)
> \- \[\] Added \[license\](https://github.com/InsightSoftwareConsortium/ITK/blob/master/Utilities/KWStyle/ITKHeader.h) to new files (if any)
> \- \[\] Added Python wrapping to new files (if any) as described in \[ITK Software Guide\](https://itk.org/ItkSoftwareGuide.pdf) Section 9.5
> \- \[\] Added \[ITK examples\](https://github.com/InsightSoftwareConsortium/ITKSphinxExamples) for all new major features (if any)
> 
> Refer to the \[ITK Software Guide\](https://itk.org/ItkSoftwareGuide.pdf) for
> further development details if necessary.

I have noticed that the [ITK doxygen](https://itk.org/Doxygen/html/index.html) has a time stamp of Jan 18. After trying another web browser and clearing the cache to make sure it was not the odd ITK cache thing going on the old data remained. So I am concluding the the ITK doxygen has not been updated in almost a month.

I was able to check the GHPages based documentation, and it appears the [ImageBase::~ImageBase](https://blowekamp.github.io/ITKDoxygen/classitk_1_1ImageBase.html#ae32541102de75266087cad089d63aed5) no longer has the erroneous doc string, along with many other methods.

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [March 18, 2022, 1:21pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/4 "2022-03-18T13:21:54Z")

</div>

@matt.mccormick @dzenanz @hjmjohnson The [itk.org](http://itk.org) nightly Doxygen has not been updated. Should this repo be move to the [InsightSoftwareConsortium](https://github.com/InsightSoftwareConsortium/) ?

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [March 18, 2022, 3:58pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/5 "2022-03-18T15:58:14Z")

</div>

[Doxygen build](https://open.cdash.org/build/7801615) succeeded without errors or warnings. Maybe @Jake_Stookey could look into `blaster` machine and why the documentation is not published?

@hjmjohnson is [PR 3311](https://github.com/InsightSoftwareConsortium/ITK/pull/3311) attempting to fix it? Or just make the existing process more efficient?

As for [Brad’s ITKDoxygen](https://github.com/blowekamp/ITKDoxygen), it should be moved to [InsightSoftwareConsortium organization](https://github.com/InsightSoftwareConsortium/ITKDoxygen) and the search issue fixed before we can switch to that as the official documentation build process. @blowekamp do you need any special permissions from Kitware sysadmin team to make the switch?

---

<div class="post-metadata">

### Author: ![Jake\_Stookey](https://discourse.itk.org/user_avatar/discourse.itk.org/jake_stookey/32/2270_2.png) [@Jake\_Stookey](https://discourse.itk.org/u/Jake_Stookey)
#### Post date: [March 18, 2022, 4:20pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/6 "2022-03-18T16:20:33Z")

</div>

> [@dzenanz](#):
>
> [Doxygen build](https://open.cdash.org/build/7801615) succeeded without errors or warnings. Maybe @Jake_Stookey could look into `blaster` machine and why the documentation is not published?

We can help if it’s something on the server end, but SysAdmins don’t typically get into the developer process of pushing this out. Maybe @matt.mccormick can look into it on Blaster?

The server to push it out to changed: it used to need to be pushed to [public.kitware.com](http://public.kitware.com), and now it needs to be pushed to [web.kitware.com](http://web.kitware.com) (or simply [itk.org](http://itk.org) which is hosted on that system). So that might be something to look into first.

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [March 18, 2022, 4:50pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/7 "2022-03-18T16:50:58Z")

</div>

I updated the script which was pushing docs, changing `public` into `web`. I guess we will know tomorrow whether that worked.

---

<div class="post-metadata">

### Author: ![hjmjohnson](https://discourse.itk.org/user_avatar/discourse.itk.org/hjmjohnson/32/23_2.png) [@hjmjohnson](https://discourse.itk.org/u/hjmjohnson)
#### Post date: [March 19, 2022, 12:48pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/8 "2022-03-19T12:48:52Z")

</div>

@dzenanz[PR 3311](https://github.com/InsightSoftwareConsortium/ITK/pull/3311) is not related to this thread or errors. That work is focused on making the wrapping easier to debug with the ultimate goal of fixing the type hints generation.

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [March 20, 2022, 11:36am UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/9 "2022-03-20T11:36:10Z")

</div>

I guess that didn’t work. Docs footer still says “Generated on Tue, 18 Jan 2022 06:30:40 +0000”.

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [March 21, 2022, 7:41pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/10 "2022-03-21T19:41:15Z")

</div>

The repository has been moved to be under the InsightConsortium:

> **[GitHub - InsightSoftwareConsortium/ITKDoxygen: ITK Doxygen nightly built with...](https://github.com/InsightSoftwareConsortium/ITKDoxygen)**
>
> ITK Doxygen nightly built with GitHub Actions and published to GitHub Pages - GitHub - InsightSoftwareConsortium/ITKDoxygen: ITK Doxygen nightly built with GitHub Actions and published to GitHub Pages

And the pages here: [ITK: Insight Toolkit](https://insightsoftwareconsortium.github.io/ITKDoxygen/)

There are some problems with the GH builds. Hopefully this PR fixes them:

> <https://github.com/InsightSoftwareConsortium/ITK/pull/3319>
>
> When ITK\_DOXYGEN\_XML was enabled XML was not being produced. These
> options were… omitted from the configuration file.
> 
> \<!-- The text within this markup is a comment, and is intended to provide
> guidelines to open a Pull Request for the ITK repository. This text will not
> be part of the Pull Request. --\>
> 
> 
> \<!-- See the CONTRIBUTING (CONTRIBUTING.md) guide. Specifically:
> 
> Start ITK commit messages with a standard prefix (and a space):
> 
> \* BUG: fix for runtime crash or incorrect result
> \* COMP: compiler error or warning fix
> \* DOC: documentation change
> \* ENH: new functionality
> \* PERF: performance improvement
> \* STYLE: no logic impact (indentation, comments)
> \* WIP: Work In Progress not ready for merge
> 
> Provide a short, meaningful message that describes the change you made.
> 
> When the PR is based on a single commit, the commit message is usually left as
> the PR message.
> 
> A reference to a related issue or pull request (https://help.github.com/articles/basic-writing-and-formatting-syntax/#referencing-issues-and-pull-requests)
> in your repository. You can automatically
> close a related issues using keywords (https://help.github.com/articles/closing-issues-using-keywords/)
> 
> @mentions (https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-people-and-teams)
> of the person or team responsible for reviewing proposed changes. --\>
> 
> \## PR Checklist
> \- \[\] No \[API changes\](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md#breaking-changes) were made (or the changes have been approved)
> \- \[\] No \[major design changes\](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md#design-changes) were made (or the changes have been approved)
> \- \[\] Added test (or behavior not changed)
> \- \[\] Updated API documentation (or API not changed)
> \- \[\] Added \[license\](https://github.com/InsightSoftwareConsortium/ITK/blob/master/Utilities/KWStyle/ITKHeader.h) to new files (if any)
> \- \[\] Added Python wrapping to new files (if any) as described in \[ITK Software Guide\](https://itk.org/ItkSoftwareGuide.pdf) Section 9.5
> \- \[\] Added \[ITK examples\](https://github.com/InsightSoftwareConsortium/ITKSphinxExamples) for all new major features (if any)
> 
> Refer to the \[ITK Software Guide\](https://itk.org/ItkSoftwareGuide.pdf) for
> further development details if necessary.

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [April 13, 2022, 5:10pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/11 "2022-04-13T17:10:39Z")

</div>

Most of the kinks with the ITK Doxygen changes have been worked out and address to the ITKDoxygen Github Action is now daily publishing the generated Doxygen here:

[https://insightsoftwareconsortium.github.io/ITKDoxygen/index.html](https://insightsoftwareconsortium.github.io/ITKDoxygen/index.html)

The search is also fixed, by using the client side search of the index. It may be slower than the server size, there is no option to run PHP on GitHub Pages.

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [April 13, 2022, 5:36pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/12 "2022-04-13T17:36:20Z")

</div>

What would it take to move “Detailed Description” to the top of the page? It is almost always more important than “Public Types” etc.

Minor: [AddImageFilter docs](https://insightsoftwareconsortium.github.io/ITKDoxygen/classAddImageFilter.html) look incomplete and strange.

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [April 13, 2022, 5:55pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/13 "2022-04-13T17:55:20Z")

</div>

> What would it take to move “Detailed Description” to the top of the page? It is almost always more important than “Public Types” etc.

That has been like that, and is not a “bug”.

> Minor: [AddImageFilter docs](https://insightsoftwareconsortium.github.io/ITKDoxygen/classAddImageFilter.html) look incomplete and strange.

Agreed. Something is off there. And the Sphinx links are broken, and the figures don’t seems to be working… many issue.

But it’s running right now. Lets get this currently proposed search fix/improvement in. And hopefully once the Doxygen on GHA is running regularly, the community can be help with some of the remaining issues.

---

<div class="post-metadata">

### Author: ![dzenanz](https://discourse.itk.org/user_avatar/discourse.itk.org/dzenanz/32/1093_2.png) [@dzenanz](https://discourse.itk.org/u/dzenanz)
#### Post date: [April 13, 2022, 6:02pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/14 "2022-04-13T18:02:14Z")

</div>

> [@blowekamp](#):
>
> not a “bug”

I always assumed it is not a bug, but I don’t like this layout. Can we change it easily? If so, we could put it up for a vote?

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [April 13, 2022, 6:04pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/15 "2022-04-13T18:04:28Z")

</div>

It looks like a custom layout may be needed:

> **[Doxygen Manual: Customizing the output](https://www.doxygen.nl/manual/customize.html#layout)**
>
> Source code documentation and analysis tool

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [May 12, 2022, 2:33pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/16 "2022-05-12T14:33:36Z")

</div>

@blowekamp this is looking great!

Is it possible to publish and link to the html, xml, and tag tarballs in the output HTML? It looks like there is some work to upload the xml on GitHub Actions.

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [May 12, 2022, 2:43pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/17 "2022-05-12T14:43:49Z")

</div>

> [@matt.mccormick](#):
>
> Is it possible to publish and link to the html, xml, and tag tarballs in the output HTML? It looks like there is some work to upload the xml on GitHub Actions.

Currently, the tarball for both the HTML and XML are uploaded as a single Github Artifact named “doxygen”. I’m not sure linking to the Github Action Artifact is the thing todo. Uploading the generated files to an archive like S3 or Kitware Data seems like a better location to store the artifice for public consumptions and downloading.

The other issue with the Doxygen generation/configuration is a “dot” executable issue:

```auto
Generating dependency graph for group Registrsh: 1: /usr/sbin/dot: not found
10339
/work/ITK-bld/Utilities/Doxygen/Modules/ITKCommon.dox:24: error: Problems running dot: exit code=127, command='/usr/sbin/dot', arguments='"/work/ITK-bld/Utilities/Doxygen/html/inline_dotgraph_1.dot" -Tsvg -o "/work/ITK-bld/Utilities/Doxygen/html/dot_inline_dotgraph_1.svg"'

```

The figures are not currently being generated.

Overall it seems to be working well it just needs a couple contributions and fixed to be 💯

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [May 12, 2022, 5:31pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/18 "2022-05-12T17:31:33Z")

</div>

> [@Jake\_Stookey](#):
>
> now it needs to be pushed to [web.kitware.com](http://web.kitware.com)

I am taking a look at this.

---

<div class="post-metadata">

### Author: ![matt.mccormick](https://discourse.itk.org/user_avatar/discourse.itk.org/matt.mccormick/32/7_2.png) [@matt.mccormick](https://discourse.itk.org/u/matt.mccormick)
#### Post date: [May 12, 2022, 5:35pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/19 "2022-05-12T17:35:07Z")

</div>

> [@blowekamp](#):
>
> I’m not sure linking to the Github Action Artifact is the thing todo.

Right – I believe they are cleaned up after a certain time period. It may be better to push to a GitHub Release Artifact on the repository – for tagged releases, then a `latest`, etc. for the latest.

> Generating dependency graph for group Registrsh: 1: /usr/sbin/dot:

Installing the `graphviz` package should fix this.

---

<div class="post-metadata">

### Author: ![blowekamp](https://discourse.itk.org/user_avatar/discourse.itk.org/blowekamp/32/79_2.png) [@blowekamp](https://discourse.itk.org/u/blowekamp)
#### Post date: [May 12, 2022, 5:57pm UTC](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790/20 "2022-05-12T17:57:39Z")

</div>

> [@matt.mccormick](#):
>
> Right – I believe they are cleaned up after a certain time period. It may be better to push to a GitHub Release Artifact on the repository – for tagged releases, then a `latest`, etc. for the latest.

Ah, good suggestions. That should work well even for ITK tags too with a little more work.

> [@matt.mccormick](#):
>
> Installing the `graphviz` package should fix this.

Unfortunately it appears to be more complicated than that as it is already installed.

> <https://github.com/InsightSoftwareConsortium/ITKDoxygen/blob/master/Dockerfile#L12>

The above error message is picking up `/usr/sbin/dot` despite the package providing [/usr/bin/dot](https://packages.ubuntu.com/focal/amd64/graphviz/filelist). It needs further investigation.

[Next page](https://discourse.itk.org/t/doxygen-with-github-actions-and-pages/4790.md?page=2)