Let me now then sing the praises of "Read the Docs" and the toolchain that gets us there.
I had used rtd before to read docs for other software (such as pybind11), but this was the first time I used it on my own projects. The hosting is super easy -- basically you just point it at any GitHub project that has a ".readthedocs.yml" and a Sphinx-based documentation with a "conf.py" file somewhere, and every time you push to that project, it will do a docs build and host the results. It's very much like using Travis-CI or Appveyor for your CI on the code itself. It knows the version, so will (as we move forward) make it easy to see the docs for any particular version you are interested in. It couldn't be simpler. With literally 30 years of experience writing book-length works in LaTeX (MS thesis, PhD dissertation, ARMan book, a dozen sets of SIGGRAPH course notes, and probably 6 or 8 sets of product documentation each in the multi-hundred page range), my Sphinx/rST skills are a little rough around the edges in comparison, and the PDF version is not as polished as what I was getting with LaTeX. But I think this is "good enough" for now, and offset by the fact that it makes a really nice set of web pages, which I didn't have before. I think Doxygen-based web pages look like complete crap on their own, but I'm finding it pretty nice to use Doxygen to scrape the code declaration comments and output to *XML* (I didn't realize that was an option), and then use "Breathe" (https://breathe.readthedocs.io) which is a plug-in that lets you reference by name a function or class from Sphinx, and it will look for the Doxygen XML and render it all out readably in the Sphinx style. Thus, there is no longer any possible mismatch between the way a function is declared in the code comments, and the way it is described in the docs. After a little more polish, I'll remove the LaTeX docs (I don't want to have to maintain both separately) and remove the PDF from the OIIO repo. The new PDFs that match the html are also hosted on the readthedocs site and also are regenerated every time there is a checkin. -- lg > On Jul 6, 2019, at 2:45 PM, Colin Doncaster <[email protected]> wrote: > > Fantastic! > >> On Jul 6, 2019, at 4:18 PM, Larry Gritz <[email protected]> wrote: >> >> I've spent the last several weekends and many evenings doing a great big >> translation of OIIO's main documentation from LaTeX (with icky, sometimes >> diverged or incorrect, redundancy between the tex and comments in the source >> code) into a combination of Doxygen and Sphinx with Breathe extensions. >> >> It is not "done", I'm sure I've left things out and botched a bunch and have >> many bits not quite right. I know for sure that references and cross-links >> within the document are mostly not working yet. But the words, code, and >> images seem to mostly have made the conversion. >> >> I also set up a readthedocs account to automatically build and host both >> HTML and PDF versions of the documentation. >> >> Preview is here: https://openimageio.readthedocs.io >> >> Please be patient, this is ongoing work. But I think it's usable, and very >> close to the point where I will stop maintaining the LaTeX-based >> documentation entirely and switch to this as the main source of docs. >> >> Feedback appreciated. >> >> -- >> Larry Gritz >> [email protected] >> >> >> >> >> _______________________________________________ >> Oiio-dev mailing list >> [email protected] >> http://lists.openimageio.org/listinfo.cgi/oiio-dev-openimageio.org > > _______________________________________________ > Oiio-dev mailing list > [email protected] > http://lists.openimageio.org/listinfo.cgi/oiio-dev-openimageio.org > -- Larry Gritz [email protected]
_______________________________________________ Oiio-dev mailing list [email protected] http://lists.openimageio.org/listinfo.cgi/oiio-dev-openimageio.org
