Create and publish a PDF of the METexpress User's Guide

[ksearight]

Replace italics below with details for this issue.

Describe the Task

As of METexpress-3.0.1, the User's Guide is created via Sphinx and the resulting html output is published to:
https://dtcenter.github.io/METexpress/development/Users_Guide/index.html

This task is to render the User's Guides as a PDF file which would useful for offline viewing. Some users, particularly in secure areas, do not have ready access to the internet for viewing docs on github.io. There is a PDF version for 3.0.1 currently available on dtcenter.org, but this was created from a Word document, not the Sphinx rst files.

Time Estimate

Estimate the amount of work required here.
Issues should represent approximately 1 to 3 days of work.

Sub-Issues

Consider breaking the task down into sub-issues.

• Add a checkbox for each sub-issue here.

Relevant Deadlines

List relevant project deadlines here or state NONE.

Funding Source

Define the source of funding and account keys here or state NONE.

Define the Metadata

Assignee

• Select engineer(s) or no engineer required
• Select scientist(s) or no scientist required

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Review projects and select relevant Repository and Organization ones or add "alert:NEED PROJECT ASSIGNMENT" label
• Select milestone to next major version milestone or "Future Versions"

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus: Generate PDF of User's Guide #551
• MET: Create and publish a PDF of the MET User's Guide for version 10.0.0. #1453

Task Checklist

See the METplus Workflow for details.

• Complete the issue definition above, including the Time Estimate and Funding Source.
• Fork this repository or create a branch of development.
  Branch name: feature_19_pdf_doc
• Complete the development and test your changes.
• Add/update log messages for easier debugging.
• Add/update unit tests.
• Add/update documentation.
• Push local changes to GitHub.
• Submit a pull request to merge into development.
  Pull request: feature 19 PDF Doc
• Define the pull request metadata, as permissions allow.
  Select: Reviewer(s), Project(s), Milestone, and Linked issues
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.

[ksearight]

This is the development version of the PDF generated from Sphinx rst files METexpress_Users_Guide_vdevelopment.pdf to be reviewed.
For reference, here is the currently published PDF, created from MS Word: METexpress Users Guide.pdf.

A few points about the generated PDF:

1. There is a TOC, but not a cover page
2. There is no index, it just has "genindex" and "search" at the end of the document
3. Page numbers are in the lower left
4. The sections and figures are not numbered
5. Long code blocks have smaller font sizes rather than wrapping.

@bonnystrong @jprestop I haven't found a way to resolve these formatting issues and differences, so my question is whether or not this formatting is sufficient "as is" for the next release version of the User Guide or not. It may be necessary to edit the rst files, which may affect the HTML version of the document as well. Please add your comments and opinions on "doneness" for this.

[bonnystrong]

Keith, I see one problem right away that I think is a show stopper. There is no numbering of sections, nothing to indicate different levels of headers. I can't follow the documentation without those levels.

…

On Wed, Mar 3, 2021 at 2:21 PM Keith Searight ***@***.***> wrote: This is the development version of the PDF generated from Sphinx rst files METexpress_Users_Guide_vdevelopment.pdf <https://github.com/dtcenter/METexpress/files/6079168/METexpress_Users_Guide_vdevelopment.pdf> to be reviewed. For reference, here is the currently published PDF, created from MS Word: METexpress Users Guide.pdf <https://github.com/dtcenter/METexpress/files/6079179/METexpress.Users.Guide.pdf> . A few points in the generated PDF: 1. There is TOC, but not a cover page 2. There is no index, it just has "genindex" and "search" at the end of the document 3. Page numbers are in the lower left 4. The sections and figures are not numbered 5. Long code blocks have smaller font sizes rather than wrapping. @bonnystrong <https://github.com/bonnystrong> @jprestop <https://github.com/jprestop> I haven't found a way to resolve these formatting issues and differences, so my question is whether or not this formatting is sufficient "as is" for the next release version of the User Guide or not. It may be necessary to edit the rst files, which may affect the HTML version of the document as well. Please add your comments and opinions on "doneness" for this. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG6HZOUQNHUPUJZJJYQU5KLTB2RZBANCNFSM4YEZEXQQ> .

-- Bonny Strong NOAA/GSL and CIRA office: 303 497-3936 or home: 970-669-6318

[jprestop]

@ksearight Thanks so much for the links to both PDFs. It was helpful to do a comparison. I don't have a problem with the sections not being numbered. I think the size of the text and the table of contents denotes the levels of headers. One thing I noticed was that the text refers to figure numbers (e.g. Figure 3.6), but the figures aren't labelled. If we can't get the figures to be labelled, we could consider replacing the text "Figure 3.6", for example, with the text that does show up under the figure and put it in quotes or something like that.

[bonnystrong]

Well I wrote it and I can't follow it without headers

…

On Wed, Mar 3, 2021 at 3:55 PM jprestop ***@***.***> wrote: @ksearight <https://github.com/ksearight> Thanks so much for the links to both PDFs. It was helpful to do a comparison. I don't have a problem with the sections not being numbered. I think the size of the text and the table of contents denotes the levels of headers. One thing I noticed was that the text refers to figure numbers (e.g. Figure 3.6), but the figures aren't labelled. If we can't get the figures to be labelled, we could consider replacing the text "Figure 3.6", for example, with the text that does show up under the figure and put it in quotes or something like that. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG6HZOR3K2GRKTG35P2333DTB2437ANCNFSM4YEZEXQQ> .

-- Bonny Strong NOAA/GSL and CIRA office: 303 497-3936 or home: 970-669-6318

[jprestop]

@bonnystrong That is certainly understandable. I do feel that headers would make it much easier to follow.

[ksearight]

I've retooled the PDF creation to use ReadTheDocs attached here.

This version fixes the following problems in the previous rst2pdf version:

1. Sections and figures are numbered now, using the same numbering as in the HTML.
2. It now has a cover page, including the METexpress logo
3. Page numbers alternate on the lower left and right corners, which is formatted for printing
4. Long code blocks are wrapped now.

@bonnystrong @jprestop Please review the new PDF and let me know if this meets the criteria to be released.

[jprestop]

@ksearight Wow! This is great. I look forward to hearing how you managed to get the table of contents in place. I believe this meets the criteria for release, but will leave the decision up to @bonnystrong and the METexpress team. Thanks for all of your work on this!

[bonnystrong]

I agree, Keith, this does look great. I would be happy for it to be released. I have a few comments that are not critical to release it, but I'll pass them on. Spacing off: on pages 26 and 52 there's a lot of blank space between bulleted items Blank pages: blank pages have been inserted on pages 54 and 58 Indices and tables: page 59, has 2 bullets that say genindex and search; is that what is expected? Chapter 7 Indices and tables • genindex • search

…

On Fri, Mar 19, 2021 at 5:39 PM jprestop ***@***.***> wrote: @ksearight <https://github.com/ksearight> Wow! This is great. I look forward to hearing how you managed to get the table of contents in place. I believe this meets the criteria for release, but will leave the decision up to @bonnystrong <https://github.com/bonnystrong> and the METexpress team. Thanks for all of your work on this! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG6HZOQZWQANUH2XH4YH7STTEPOBRANCNFSM4YEZEXQQ> .

-- Bonny Strong NOAA/GSL and CIRA office: 303 497-3936 or home: 970-669-6318

[mollybsmith-noaa]

Hi Julie, Keith, Bonny, First off, thanks Keith, this looks excellent! It’ll be nice to have a PDF version to scroll through. I did just update the Sphinx code for the METexpress user’s guide on the development branch. Sorry about the timing, but between the addition of vector statistics in v4.0.0 and the interp_mthd/grid_scale selectors in v4.0.1, the app descriptions we had were no longer fully accurate. I pushed these changes to origin/development, but is there anything special that I need to do when we end up releasing an update? Finally, METexpress does still need to have a release guide, but I’m not sure how to inherit parts of that from METplus (I think we’re supposed to?) and I need to meet with Julie about that at some point. Not next week, I’m in a workshop the whole time. Have a good weekend! Molly

…

On Mar 19, 2021, at 6:09 PM, bonnystrong ***@***.***> wrote: I agree, Keith, this does look great. I would be happy for it to be released. I have a few comments that are not critical to release it, but I'll pass them on. Spacing off: on pages 26 and 52 there's a lot of blank space between bulleted items Blank pages: blank pages have been inserted on pages 54 and 58 Indices and tables: page 59, has 2 bullets that say genindex and search; is that what is expected? Chapter 7 Indices and tables • genindex • search On Fri, Mar 19, 2021 at 5:39 PM jprestop ***@***.***> wrote: > @ksearight <https://github.com/ksearight> Wow! This is great. I look > forward to hearing how you managed to get the table of contents in place. I > believe this meets the criteria for release, but will leave the decision up > to @bonnystrong <https://github.com/bonnystrong> and the METexpress team. > Thanks for all of your work on this! > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#19 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AG6HZOQZWQANUH2XH4YH7STTEPOBRANCNFSM4YEZEXQQ> > . > -- Bonny Strong NOAA/GSL and CIRA office: 303 497-3936 or home: 970-669-6318 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHBWGZI5D6Z2RZGQX5B57XTTEPRTZANCNFSM4YEZEXQQ>.

[ksearight]

@bonnystrong Thanks for reviewing. Here are responses to your findings:

• I'll see if the blank space on p. 26 & 52 can be fixed in the rst files.
• I think the blank pages on p. 54 & 58 are intentional by ReadThe Docs so that new chapters always begin on an odd numbered page. Formatting it that way will always put new chapters on the front side of the paper when printed double-sided. I don't know if that can be turned off or not.
• I'll see if the index chapter can be skipped for PDFs. This is happening for the METplus user guide too.

@mollybsmith-noaa I'll merge your changes from development back into my feature branch and regenerate the doc so we see how it looks in PDF.

[mollybsmith-noaa]

Excellent, thanks Keith! Molly

…

On Mon, Mar 22, 2021 at 1:35 PM Keith Searight ***@***.***> wrote: @bonnystrong <https://github.com/bonnystrong> Thanks for reviewing. Here are responses to your findings: - I'll see if the blank space on p. 26 & 52 can be fixed in the rst files. - I think the blank pages on p. 54 & 58 are intentional by ReadThe Docs so that new chapters always begin on an odd numbered page. Formatting it that way will always put new chapters on the front side of the paper when printed double-sided. I don't know if that can be turned off or not. - I'll see if the index chapter can be skipped for PDFs. This is happening for the METplus user guide too. @mollybsmith-noaa <https://github.com/mollybsmith-noaa> I'll merge your changes from development back into my feature branch and regenerate the doc so we see how it looks in PDF. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHBWGZNJX3AHPVDP2FJAD43TE6LXPANCNFSM4YEZEXQQ> .

[ksearight]

Here's an updated version of the PDF. I made these changes:

1. Reduced the blank lines with rst file changes. It also changed the appearance in the HTML version slightly.
2. Commented out the "Indices and tables" section in the rst file. It no longer appears in the HTML version either, but in the ReadTheDocs build, those links went to empty pages anyway.
3. Merged in changes made to the development branch.

@bonnystrong @mollybsmith-noaa Please take a look and let me know what you think.

[mollybsmith-noaa]

Looks great to me! We should probably update the screenshots at some point to reflect the new selectors in 4.0.1, but these still illustrate everything that needs illustrating, so I don’t think that’s a high priority. Molly

…

On Tue, Mar 23, 2021 at 4:20 PM Keith Searight ***@***.***> wrote: Here's an updated version of the PDF <https://github.com/dtcenter/METexpress/files/6193002/metexpress-readthedocs-io-en-latest.pdf>. I made these changes: 1. Reduced the blank lines with rst file changes. It also changed the appearance in the HTML version slightly. 2. Commented out the "Indices and tables" section in the rst file. It no longer appears in the HTML version either, but in the ReadTheDocs build, those links went to empty pages anyway. 3. Merged in changes made to the development branch. @bonnystrong <https://github.com/bonnystrong> @mollybsmith-noaa <https://github.com/mollybsmith-noaa> Please take a look and let me know what you think. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHBWGZION5UJIA4PDXBQIV3TFEHXXANCNFSM4YEZEXQQ> .

[bonnystrong]

It looks good to me. I have one change I would like to see in this or in the future. Last page that shows link to EMC installation says "available here (with link)". I would like to put actual URL in place of "here", so a printed version has the info available. It's also an important question about the version. I had thought when we have a major release (like 4.0.0) which I assume will be no more than once a year, we need to review the documentation to be sure it is still compatible. We shouldn't be just sticking a new version num on the title page. From Molly's email, evidently there are changes in the menus. I think Molly is the only one who knows what needs to be changed. Molly, can you take that on with a major release?

…

On Tue, Mar 23, 2021 at 4:20 PM Keith Searight ***@***.***> wrote: Here's an updated version of the PDF <https://github.com/dtcenter/METexpress/files/6193002/metexpress-readthedocs-io-en-latest.pdf>. I made these changes: 1. Reduced the blank lines with rst file changes. It also changed the appearance in the HTML version slightly. 2. Commented out the "Indices and tables" section in the rst file. It no longer appears in the HTML version either, but in the ReadTheDocs build, those links went to empty pages anyway. 3. Merged in changes made to the development branch. @bonnystrong <https://github.com/bonnystrong> @mollybsmith-noaa <https://github.com/mollybsmith-noaa> Please take a look and let me know what you think. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AG6HZOXLM62GFCRJ7TSZHC3TFEHXXANCNFSM4YEZEXQQ> .

-- Bonny Strong NOAA/GSL and CIRA office: 303 497-3936 or home: 970-669-6318

[randytpierce]

I think it's beautiful! randy On Tue, Mar 23, 2021 at 5:41 PM bonnystrong ***@***.***> wrote:

…

It looks good to me. I have one change I would like to see in this or in the future. Last page that shows link to EMC installation says "available here (with link)". I would like to put actual URL in place of "here", so a printed version has the info available. It's also an important question about the version. I had thought when we have a major release (like 4.0.0) which I assume will be no more than once a year, we need to review the documentation to be sure it is still compatible. We shouldn't be just sticking a new version num on the title page. From Molly's email, evidently there are changes in the menus. I think Molly is the only one who knows what needs to be changed. Molly, can you take that on with a major release? On Tue, Mar 23, 2021 at 4:20 PM Keith Searight ***@***.***> wrote: > Here's an updated version of the PDF > < https://github.com/dtcenter/METexpress/files/6193002/metexpress-readthedocs-io-en-latest.pdf >. > I made these changes: > > 1. Reduced the blank lines with rst file changes. It also changed the > appearance in the HTML version slightly. > 2. Commented out the "Indices and tables" section in the rst file. It > no longer appears in the HTML version either, but in the ReadTheDocs build, > those links went to empty pages anyway. > 3. Merged in changes made to the development branch. > > @bonnystrong <https://github.com/bonnystrong> @mollybsmith-noaa > <https://github.com/mollybsmith-noaa> Please take a look and let me know > what you think. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#19 (comment) >, > or unsubscribe > < https://github.com/notifications/unsubscribe-auth/AG6HZOXLM62GFCRJ7TSZHC3TFEHXXANCNFSM4YEZEXQQ > > . > -- Bonny Strong NOAA/GSL and CIRA office: 303 497-3936 or home: 970-669-6318 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGDVQPSNTHUN56YKDOUZFHDTFEREZANCNFSM4YEZEXQQ> .

-- Randy Pierce

[ksearight]

I changed the Appendix A to show the emc link instead of "here". I think it's ready for a pull request now.

[mollybsmith-noaa]

I do think we should only do one major release per year if we’re doing coordinated releases with DTC, but I can definitely update the screenshots to be in line with that release. We picked up a couple of extra selectors, but they don’t affect any of the functionality specifically discussed by the text, they are just presented in the lists of selectors for the relevant apps. I was comfortable including those in v4.0.1 because they don’t affect backwards compatibility at all. The 4.0.0 apps can run with the 4.0.1 metadata. Molly

…

On Tue, Mar 23, 2021 at 5:50 PM Keith Searight ***@***.***> wrote: I changed the Appendix A to show the emc link instead of "here". I think it's ready for a pull request now. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHBWGZML2DGX46IE7OY2U43TFESMRANCNFSM4YEZEXQQ> .