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.

[brainwane]

We hit the September milestone when we gave our stakeholders a one-off bundle; this issue is now for making that repeatable.

[cecilia-donnelly]

For the next phase, the documents we'll want to bundle are:

• ICD document, largely a wrapper around the LEIE API docs, TBD (@cecilia-donnelly will do in Document application architecture and interfaces #466)
  • LEIE API documentation (see Write LEIE API documentation: #446 #558)
• Architecture documents:
  • Diagrams sent to the psm-dev list
  • Schema diagrams in Document application architecture and interfaces #466

Internally, there are plans for a Word-formatted user manual. It might be hard to bundle that with these other items, but we should refer to it in the TOC.

[brainwane]

I've spruced up my work in https://github.com/brainwane/psm/tree/make-zip-of-dox a bit and refamiliarized myself with it, and updated it to wget the architectural diagrams (this is a hack to prevent unnecessarily having those in the repo, but I'm happy to add them to the repo instead if desired). My next step is to add the architectural diagrams to the table of contents, and to mark where we'll include the LEIE API docs.

[cecilia-donnelly]

@brainwane I added an ICD in #592, if you could review that and include it in your bundle.

[brainwane]

I reviewed #592 but haven't added it yet to the PR yet since we haven't merged it. I'll figure out a way to include it anyway....

[cecilia-donnelly]

@brainwane, can this be closed? We've successfully created the bundle a couple times, and now have a script that we can work from for future iterations.

[brainwane]

Sure!

🎉