[vtkusers] [vtk-developers] Request for Feedback: VTK Textbook Strawman

[David Thompson]

> pandoc is not perfect, but I did use it to convert the book's pdf to
> markdown doc, docx and txt.

I believe pandoc also deals with restructured text (rst), which is similar to markdown. It is what https://readthedocs.org/ uses (via the python Sphinx tool). We use it for some other projects at Kitware (SMTK and CMB) and it works well. Unlike markdown, it is extensible (you can write python code to inject HTML/JS/LaTeX etc. into the output).

It also has some hooks to include portions of external files. We use this to directly include source code (that gets tested!) into the documentation. I am working toward using image tests as part of the documentation. Of course, it's not perfect (there's no guarantee all the documentation makes sense anymore if you change the source). I also want to use it to inject interactive vtk-js content into the online version of the docs (and a screenshot into the offline version), which is possible via an extension if not directly.

	David