New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

bundle user & developer docs for psm-dev #458

Closed
brainwane opened this Issue Sep 27, 2017 · 13 comments

Comments

@brainwane
Contributor

brainwane commented Sep 27, 2017

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

This comment has been minimized.

Contributor

brainwane commented Sep 27, 2017

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

This comment has been minimized.

Contributor

brainwane commented Sep 28, 2017

@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

This comment has been minimized.

Contributor

brainwane commented Sep 28, 2017

@brainwane brainwane added this to the September Requirements milestone Sep 28, 2017

brainwane added a commit to brainwane/psm that referenced this issue Sep 28, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.

@brainwane brainwane changed the title from one-time: bundle user & developer docs for psm-dev to bundle user & developer docs for psm-dev Sep 28, 2017

@brainwane

This comment has been minimized.

Contributor

brainwane commented Sep 28, 2017

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

@brainwane

This comment has been minimized.

Contributor

brainwane commented Sep 28, 2017

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

brainwane added a commit to brainwane/psm that referenced this issue Sep 29, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.
@brainwane

This comment has been minimized.

Contributor

brainwane commented Sep 29, 2017

This psm-dev post includes an example ZIP output.

@brainwane

This comment has been minimized.

Contributor

brainwane commented Oct 31, 2017

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

@cecilia-donnelly

This comment has been minimized.

cecilia-donnelly commented Dec 13, 2017

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 #466)
    • LEIE API documentation (see #558)
  • Architecture documents:

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 added a commit to brainwane/psm that referenced this issue Dec 26, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.

brainwane added a commit to brainwane/psm that referenced this issue Dec 26, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.

brainwane added a commit to brainwane/psm that referenced this issue Dec 26, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.
@brainwane

This comment has been minimized.

Contributor

brainwane commented Dec 26, 2017

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.

brainwane added a commit to brainwane/psm that referenced this issue Dec 27, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.

brainwane added a commit to brainwane/psm that referenced this issue Dec 27, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.
@cecilia-donnelly

This comment has been minimized.

cecilia-donnelly commented Dec 29, 2017

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

brainwane added a commit to brainwane/psm that referenced this issue Dec 31, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script builds PDFs of our prose documents for users, administrators,
and developers, builds the HTML documentation for our API, and puts
together a ZIP file with an HTML index page to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need several Python & Debian packages
installed; see `docs/userhelp/README.mdwn`.

Fixes SolutionGuidance#458.

brainwane added a commit to brainwane/psm that referenced this issue Dec 31, 2017

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script creates a temporary directory, builds PDFs of our prose
documents for users, administrators, and developers, builds the HTML
documentation for our API, downloads PDFs and PNG images of
architectural and schema diagrams, and puts together a ZIP file with a
PDF index page with clickable links to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need some Debian packages installed;
see `docs/userhelp/README.mdwn`.

Towards SolutionGuidance#458.
@brainwane

This comment has been minimized.

Contributor

brainwane commented Dec 31, 2017

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....

brainwane added a commit to brainwane/psm that referenced this issue Jan 5, 2018

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script creates a temporary directory, builds PDFs of our prose
documents for users, administrators, and developers, builds the HTML
documentation for our API, downloads PDFs and PNG images of
architectural and schema diagrams, and puts together a ZIP file with
an HTML index page with clickable links to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need some Debian packages installed;
see `docs/userhelp/README.mdwn`.

Towards SolutionGuidance#458.

brainwane added a commit to brainwane/psm that referenced this issue Jan 5, 2018

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script creates a temporary directory, builds PDFs of our prose
documents for users, administrators, and developers, builds the HTML
documentation for our API, pulls in PDFs and PNG images of
architectural and schema diagrams, and puts together a ZIP file with
a lightly styled HTML index page with clickable links to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need some Debian packages installed;
see `docs/userhelp/README.mdwn`.

Towards SolutionGuidance#458.

brainwane added a commit to brainwane/psm that referenced this issue Jan 5, 2018

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script creates a temporary directory, builds PDFs of our prose
documents for users, administrators, and developers, builds the HTML
documentation for our API, pulls in PDFs and PNG images of
architectural and schema diagrams, and puts together a ZIP file with
a lightly styled HTML index page with clickable links to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need some Debian packages installed;
see `docs/userhelp/README.mdwn`.

Towards SolutionGuidance#458.

brainwane added a commit to brainwane/psm that referenced this issue Jan 5, 2018

Add script to create user and developer documentation bundle
To help us inform our stakeholders better, it's nice to have a ZIPped
archive of our user manual, developer documentation, and so on. This
script creates a temporary directory, builds PDFs of our prose
documents for users, administrators, and developers, builds the HTML
documentation for our API, pulls in PDFs and PNG images of
architectural and schema diagrams, and puts together a ZIP file with
a lightly styled HTML index page with clickable links to aid browsing.

~~~
$ cd scripts
$ ./make-zip-of-documents.sh
~~~

To run this successfully, you'll need some Debian packages installed;
see `docs/userhelp/README.mdwn`.

Towards SolutionGuidance#458.
@cecilia-donnelly

This comment has been minimized.

cecilia-donnelly commented Jan 12, 2018

@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

This comment has been minimized.

Contributor

brainwane commented Jan 12, 2018

Sure!

🎉

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment