Produce PDF document?

[tclune]

We have successfully sold our organization's management to switch over to FORD for our documentation, but there were several emphatic requests that they asked us to pursue.

The first, but possibly not the most important concern, was the lack of ability to produce a simple PDF document. Partly this just a matter of waiting for the previous generation to retire, but there are legitimate times still when we might want to produce a formal report for archiving where a PDF is a more natural fit.

How much trouble would it be to have an option to generate a pdf document? We'd hope for at least some hyperlinks to survive, of course.

[ZedThree]

Hi Tom, great to hear you've switched over to FORD!

I can think of a few ways to do this, with differing levels of difficulty and prettiness, for want of a better word:

1. Pandoc can convert HTML to PDF via LaTeX (and maybe a couple of other mechanisms). This will definitely give you something, but I don't know how it handles multiple HTML pages and the output might not be very pretty
2. We add LaTeX templates and build directly to PDF ourselves. I don't think the Python machinery to do this would be very complicated to implement, but it would require a fair bit of effort to write the templates. We'd have the most control of how it actually looks like this. This is probably achievable in a summer project with a decent student.
3. We convert FORD to be a Sphinx extension and rely on that to build HTML/PDF. That would have loads of benefits, but I'm not really sure how much effort this would take. It might be fairly trivial to add it as an option, or it might require months of effort.

If you are able to have a play with pandoc and decide it works well enough, we could add that as an option to FORD somehow. That's probably the most expedient way to do this.

[tclune]

Adding @mathomp4 and @JulesKouatchou to monitor/comment this issue. @JulesKouatchou has the lead in overhauling our documentation and will work with Pandoc to see what it generates.

[d7919]

If you have a small enough project (or enough memory) you can get a very crude pdf by doing

pandoc $(find docs/html/ -name '*.html') -s -t pdf -o docs.pdf

where docs/html is the path to your generated site. Links don't work (they still point to the html) and there is no attempt to deal with long code lines which go off the edge of the page in verbatim blocks. I suspect we would need to provide a pandoc filter to fix the links issue and we may also want a custom tex template to help out of the box appearance.