edwardhartnett
commented
4 years ago For reference, here's how I build and release documentation for the PIO project:
Update Documentation: The master branch is checked out, and configured with the --enable-docs option. (Doxygen is required). The documentation is built by doing a make in the doc directory. This produces the HTML version of the documentation in the (confusingly named) docs directory. Another clone of the library is checked out and the gh-pages branch checked out. A git rm -rf is done on the gh-pages branch to delete all files. Then the docs directory is copied there and a git add adds the files to the gh-pages branch. This is then committed and GitHub will display it as project documentation. Note that it can take some time after pushing the changes before the web page with the documentation gets updated. (See also https://stackoverflow.com/questions/11577147/how-to-fix-http-404-on-github-pages). The commands to do this:
git clone git@github.com:NCAR/ParallelIO.git p1
cd p1/
git checkout gh-pages
git rm -rf *
cp -R ../ParallelIO/docs/* .
git add *
git commit -m "updated docs" -a && git push
BenjaminTJohnson
jbathegit
All NCEPLIBS should have good doxygen documentation. A link to documentation for the most recent release is always available from the project README page, and uses GitHub gh-pages branch to publish built documentation.
Getting doxygen docs together will involve the following:
Markdown files can be incorporated into Doxygen docs directly. That is, you don't have to move your .md text into code files. Within the .md files, you can cross-reference any function by using parens after the name, and doxygen will provide the hyperlink. (So nc_create() instead of nc_create will be hyperlinked).
Fortran is a challenge with Doxygen for sure. A good example can be found in the PIO library, documentation here: https://ncar.github.io/ParallelIO/api.html.