> The new PDFs that match the html are also hosted on the readthedocs site and also are regenerated every time there is a checkin.
And they should be generated with LaTeX actually! Loop is closed :) RTD is great, can be bumpy at times though when the build fails. Things to look for especially are timeouts, I had a lot of issues where the builds were killed if taking too long in the past. Thomas Mansencal - colour-science.org <https://www.colour-science.org> - thomasmansencal.com <http://www.thomasmansencal.com> Le dim. 7 juil. 2019 à 10:33, Larry Gritz <[email protected]> a écrit : > 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 >
_______________________________________________ Oiio-dev mailing list [email protected] http://lists.openimageio.org/listinfo.cgi/oiio-dev-openimageio.org
