bundle user & developer docs for psm-dev

[brainwane]

To do:

• Turn developer/administrator prose documents (e.g., DESIGN.md, INSTALL.md, TESTING.md, CONTRIBUTING.md) into PDFs
• Generate a PDF of user documentation
• Create a zipped archive of the above PDFs, plus the Javadoc API docs (HTML), plus a textual table of contents
• Note down steps to achieving the above outcome
• On Friday, September 29, send the zipped archive to the psm-dev mailing list

[brainwane]

As long as you have some LaTeX packages installed, you can use Pandoc to turn md files into PDFs using, e.g., pandoc -t latex -o architecture-design.pdf DESIGN.md.

I right-clicked on the psm-app/cms-web/build/reports/api-docs directory in the GUI of my desktop environment, chose "Compress", and thus created a ZIP file. And then dragged the PDFs into that. Tomorrow I can figure out how to do that on the command line.

[brainwane]

@cecilia-donnelly suggests:

Can we include an introduction page, explaining what the documents in this zip archive are? Can we number them, so that people read them in a coherent order? (starting with architecture-design will be confusing, I think) Also in that intro doc, can we tell them that they should open "index.html" to view all the API docs? Better yet, can we symlink that from the top level, with some clearer name, so they don't have to look into the api-docs subdir at all?

[brainwane]

Working on this in https://github.com/brainwane/psm/tree/make-zip-of-dox .

[brainwane]

@jasonaowen has offered to Gradle-ize this, which I think is a fine idea but not essential to the September deadline.

[brainwane]

An example of the file that this script produces: https://send.firefox.com/download/58c4869834/#D07DOSX_C1hxeQNiZL4mKA

[brainwane]

This psm-dev post includes an example ZIP output.