add sphinx and doxygen tests to ci checks

[cyrush]

add basic sphinx and doxygen projects to blt-test, to exercise our docs support

[davidbeckingsale]

Are we going to use sphinx to document blt itself?

[cyrush]

we are -- not sure if that will live in the blt repo or in another one.

I am leaning more and more towards in the BLT repo via a special target.

[davidbeckingsale]

Sounds good - I was going to volunteer to help out with a user guide since I have been a user-turned-developer 😄

[rhornung67]

FWIW, I vote 1000% for keeping the blt docs in the blt repo

[zbeekman]

Not sure how you currently build & host docs, but it's fairly easy to deploy to GH-pages from Travis-CI. If you deploy the documentation from master in a continuous delivery (CD) style---which seems congruent with your recommendation of installing BLT as a submodule---then updating the documentation becomes as easy as committing changes to the rst docs.

It looks like you have a gh-pages branch but that you are not automatically deploying documentation from your CI setup.

[zbeekman]

FYI I have set this up for other projects, like JSON-Fortran: https://jacobwilliams.github.io/json-fortran/ and could take a look.

[cyrush]

@zbeekman we have wired things up to read the docs:

http://llnl-blt.readthedocs.io/en/latest/

but we haven't made that clear in our docs or in readmes in the repo.

I planned to change gh-pages to redirect to read the docs, but I haven't done that yet.

[zbeekman]

Ah, I see. Looks like the link on the README.md needs updating. I'm not experienced with readthedocs.io but I'm glad to see that there is some automation.

So is this issue open as a reminder to add more tests for the documentation generation capabilities?

[cyrush]

@zbeekman correct, we want to test blt calling doxygen and sphinx (not necessarily building the blt docs)

To be more concrete, one path to resolve this:

Setup travis with doxygen + sphinx and build the docs for the tutorial example using make docs