These are chat archives for Fortran-FOSS-Programmers/General-Discussion

23rd
Jan 2016
Neil Carlson
@nncarlson
Jan 23 2016 16:23
Workflow / best practices for automatic documentation generation (FORD)
@cmacmackin recently added support for #include in his FORD tool and I'm setting about now learning how to use it in one of my small projects. I have big questions though on what I should do with the resulting documentation. I know many of you here use it and I'm hoping to get some advice (and if not I'll be poking about in your repos to see if I can discover what you do). Some questions:
  • Should I include the doc in the git repo (the docs are completely rewritten each time FORD is run I gather), or do I treat it just as temporary data to be moved elsewhere (but where? web page, wiki?)
  • Should I use github's funky gh-pages branch as the place to permanently archive the doc? Anybody using gh-pages?
  • Related to the above is what are good ways to provide the entry point to the doc?
  • CMake magic to generate a "doc" target using FORD. Care to share?
Izaak "Zaak" Beekman
@zbeekman
Jan 23 2016 16:45

@nncarlson Interesting questions!

I am of the persuasion that the generated documentation should not be checked into your VCS system, since it is an asset that is built by the build system from the sources. My preferred place to put the docs is the gh-pages branch of your projects github repo.

For JSON-Fortran we use some "black magic" that I came up with that includes:

The entry point to the documentation can be links on the README.md and wiki if one exists, and publicizing the URL in any user manual, or project website, etc.

Neil Carlson
@nncarlson
Jan 23 2016 17:01
Thank you @zbeekman! I'll be taking a careful look at what you are doing in JSON-Fortran. My gut feeling was that the generated docs don't belong under VCS but wasn't sure what else to do with it.
Izaak "Zaak" Beekman
@zbeekman
Jan 23 2016 17:20
I think the auto-deploy with Travis-CI (and only when tests pass, and build succeeds) is pretty slick, but it was a real PITA to figure out. I hope looking at my code will help get you started with much less headache.