Skip to content
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
Closed

bundle user & developer docs for psm-dev #458

brainwane opened this issue Sep 27, 2017 · 13 comments

Comments

@brainwane
Copy link
Contributor

@brainwane 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
Copy link
Contributor Author

@brainwane 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
Copy link
Contributor Author

@brainwane 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
Copy link
Contributor Author

@brainwane 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
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 one-time: bundle user & developer docs for psm-dev bundle user & developer docs for psm-dev Sep 28, 2017
@brainwane
Copy link
Contributor Author

@brainwane 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
Copy link
Contributor Author

@brainwane 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
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
Copy link
Contributor Author

@brainwane brainwane commented Sep 29, 2017

This psm-dev post includes an example ZIP output.

@brainwane
Copy link
Contributor Author

@brainwane 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
Copy link

@cecilia-donnelly 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
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
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
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
Copy link
Contributor Author

@brainwane 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
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
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
Copy link

@cecilia-donnelly 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
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
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
Copy link
Contributor Author

@brainwane 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
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
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
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
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
Copy link

@cecilia-donnelly 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
Copy link
Contributor Author

@brainwane brainwane commented Jan 12, 2018

Sure!

🎉

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants