Open cyrush opened 7 years ago
Are we going to use sphinx to document blt itself?
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.
Sounds good - I was going to volunteer to help out with a user guide since I have been a user-turned-developer 😄
FWIW, I vote 1000% for keeping the blt docs in the blt repo
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.
FYI I have set this up for other projects, like JSON-Fortran: https://jacobwilliams.github.io/json-fortran/ and could take a look.
@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.
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?
@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
add basic sphinx and doxygen projects to blt-test, to exercise our docs support