search

NOAA-EMC / WW3

WAVEWATCH III
Other
257 stars 508 forks source link

Add doxygen to the build #1171

Closed edwardhartnett closed 2 days ago

edwardhartnett commented 6 months ago

Is your feature request related to a problem? Please describe. With other EMC packages, we have an ENABLE_DOCS cmake option, which causes the documentation to be built on make all.

This has several advantages, including ease of checking documentation build in CI and the ability to inject the software version into the documentation, which is important.

Describe the solution you'd like Add ENABLE_DOCS option to build, and test the documentation build in CI.

Describe alternatives you've considered When documenting UFS_UTILS, NCEPLIBS, UPP, and soon fv3atm, we have worked out a good way to do this which is easy for programmers.

Additional context Once we are building the documentation, we can use the gh-pages branch to display it on GitHub.

MatthewMasarik-NOAA commented 6 months ago

@edwardhartnett, I do have a PR for this capability in the works.

edwardhartnett commented 6 months ago

Oh, I have one that works that I was about to put up. It matches the way we do things in the other EMC repos to build doxygen.

It also causes the documentation to be built in CI, and then uploads a copy of the built documentation to GitHub actions, so programmers can download it, in case that is of interest.

We could also arrange to put the develop branch documentation automatically on the gh-pages branch. Typically we use the gh-pages branch for the latest released version of the doxygen docs, but I don't think you have one yet.

MatthewMasarik-NOAA commented 6 months ago

Okay let's discuss at our meeting, because I have one worked out as well. I've also set up hosting on gh-pages in the past as well, so I was going to have that be a follow on Pr.

On Fri, Jan 12, 2024 at 8:20 AM Edward Hartnett @.***> wrote:

Oh, I have one that works that I was about to put up. It matches the way we do things in the other EMC repos to build doxygen.

It also causes the documentation to be built in CI, and then uploads a copy of the built documentation to GitHub actions, so programmers can download it, in case that is of interest.

We could also arrange to put the develop branch documentation automatically on the gh-pages branch. Typically we use the gh-pages branch for the latest released version of the doxygen docs, but I don't think you have one yet.

— Reply to this email directly, view it on GitHub https://github.com/NOAA-EMC/WW3/issues/1171#issuecomment-1889187237, or unsubscribe https://github.com/notifications/unsubscribe-auth/AUV3FMG7A3CRLFFXV24MTDTYOE2ADAVCNFSM6AAAAABBYCSPS6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBZGE4DOMRTG4 . You are receiving this because you commented.Message ID: @.***>

edwardhartnett commented 6 months ago

We would like all the EMC repos to do this the same way, so let's make sure that we end up with something that looks and works the same way as NCEPLIBS, UPP, UFS_UTILS, and (soon) fv3atm.