Migrate the METexpress documentation from Word to Sphinx

[jprestop]

Describe the Task

Migrate the METexpress documentation from Word to Sphinx

Time Estimate

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

Sub-Issues

Consider breaking the task down into sub-issues.

• [x] Set up environment for Lisa to get started.
• [x] Create gh-pages branch
• [x] Create docs subdirectory
• [x] Populate the pages
• [ ] Publish using gh-pages.

Relevant Deadlines

Funding Source

Define the Metadata

Assignee

• [x] Select engineer(s) or no engineer required
• [x] Select scientist(s) or no scientist required

Labels

• [x] Select component(s)
• [ ] Select priority
• [ ] Select requestor(s)

Projects and Milestone

• [ ] Review projects and select relevant Repository and Organization ones
• [ ] Select milestone

Define Related Issue(s)

Consider the impact to the other METplus components.

• [x] METplus, MET, METdb, METviewer, METexpress, METcalcpy, METplotpy

Task Checklist

See the METplus Workflow for details.

• [x] Complete the issue definition above.
• [x] Fork this repository or create a branch of development. Branch name: feature_<Issue Number>_<Description>
• [x] Complete the task and verify your changes.
• [ ] Add/update unit tests.
• [x] Add/update documentation.
• [x] Push local changes to GitHub.
• [x] Submit a pull request to merge into development, listing the \<Issue Number> in the title.
• [x] Iterate until the reviewer(s) accept and merge your changes.
• [x] Delete your fork or branch.
• [ ] Close this issue.

[jprestop]

Notes from September 30th meeting: https://docs.google.com/document/d/1Z-rqufL_dbXTHHgNJX48pfdcuxcO2MbLeZXvE4B6qH0/edit

Per the meeting on September 30, Randy will review the front page (https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/index.html) and will add content for MATS.

Per the meeting on September 30, Bonny will:

• Review the Acknowledgements section (https://ral.ucar.edu/staff/jpresto/work/METexpress_jpresto/Users_Guide/index.html) and will decide what to put there. She can review the MET (https://dtcenter.github.io/METplus/Users_Guide/index.html) and METplus (https://dtcenter.github.io/MET/Users_Guide/index.html#) acknowledgements as a guide.
• Will check with Jason Levit regarding: Appendix A - ok to include EMC url?

Per the meeting on September 30, Lisa will:

• Implement the main content of the documentation once the Final User's Guide is received in .docx format (received) and will:
• Change to 2 levels instead of the 4 that MET has. (e.g. 2, 2.1, 2.1.1, etc.).
• Change the Terms of Use to “2020, UCAR/NCAR, NOAA, CSU/CIRA, and CU/CIRES” across all the repos (MET, METplus, METviewer, METexpress).
• Change the authors to Bonny Strong, Randy Pierce, Molly B. Smith, Venita Hagerty, and Jeff Hamilton.

Per the meeting on September 30, Julie will add information about community support to the forward using the MET (https://dtcenter.github.io/METplus/Users_Guide/index.html) and METplus (https://dtcenter.github.io/MET/Users_Guide/index.html#) Forward as a guide, but will use different language to best support the needs of METexpress.

[bonnystrong]

Jason Levit has replied that it is ok to leave in the link to the AWS METexpress in Appendix 1.

[bonnystrong]

I see this shows Milestone METexpress 4.0.0. This version should be associated with METexpress 3.0.0

[bonnystrong]

Citation: currently says "Strong, B., Pierce, R., Smith, M., Hagerty, V. ???, 2020: The METexpress Version 3.0.0 User’s Guide. Developmental Testbed Center. Available at: METexpress releases" Please add Jeff Hamilton as the 5th author.
Also, the link for "releases" shows no releases yet. There should be a METexpress release for 3.0.0, I believe, in github. But perhaps this just isn't finished yet?

[jprestop]

Thank you, Bonny. When I created this issue, Milestone METexpress 4.0.0 was the only option available. I just tried to create one, but I believe someone beat me to it. I just changed the milestone. Thanks!

[jprestop]

I have updated the forward and also went ahead and updated the author information since it was in the same file. I also updated the citation to include Jeff Hamilton as well.

And, Lisa, regarding: Change the Terms of Use to “2020, UCAR/NCAR, NOAA, CSU/CIRA, and CU/CIRES” across all the repos (MET, METplus, METviewer, METexpress).

That is contained in the docs/conf.py files. I already changed it for METexpress. Below are the changes. It was previously: author = 'UCAR/NCAR, NOAA, and CSU/CIRA' and is now: author = 'UCAR/NCAR, NOAA, CSU/CIRA, and CU/CIRES'

This still needs to be changed in MET, METplus, and METviewer, as I did not fix those.

[jprestop]

Update on documentation:

• Lisa will add the Acknowledgement section that Bonny sent to me today.
• Lisa will update some images in the document.
• Lisa will do a loose comparison and then pass it over to Julie to look at for an obvious errors, then Julie will send an email to your group to review.
• Julie will add files and modify conf.py to enable a version selector, so that different versions of the documentation can be viewed (e.g. v3.0.0, master, development, etc.)
• Randy, have you had a chance to review the front page (https://ral.ucar.edu/staff/jpresto/work/METexpress_jpresto/index.html)? We had talked about you adding history that includes MATS. You can either comment here and Lisa or I will add it, or you can modify the .rst file directly - whatever you are comfortable with.
• The writing perspective does not seem to be consistent within the METexpress User’s Guide. Sections 1 - 3 seem to be in third person ("one",), which is consistent with the other METplus components’ User’s Guides; Sections 4 and 5 seems to be in second person ("you"). Examples below. Do we want to be consistent? If you would like Sections 4 and 5 modified to be in third person, Lisa would be happy to take on this task.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/apps.html Contour: Contour plots can be used in many ways. One can illustrate data with respect to height, as in plots seen at http://www.emc.ncep.noaa.gov/gmb/STATS_vsdb/, which have height on the y-axis and forecast hour (as in lead time) on the x-axis.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/installation.html Software: You must have docker, docker-compose, httpaswd, and jq installed. You should have a certificate installed in /etc/ssl/certs, although you can deploy a simple system on localhost without certificates for testing. A simple testing system can be deployed by answering yes to the question “Are you setting up a simple test environment?” in the configure program.

[randytpierce]

I am still reviewing. Sorry for the delay. I will try to conform to a third person perspective. I think this problem came about because I originally did it in readme.md files which tended to have the second person perspective. randy

On Wed, Oct 14, 2020 at 3:34 PM jprestop notifications@github.com wrote:

Update on documentation:

• Lisa will add the Acknowledgement section that Bonny sent to me today.
• Lisa will update some images in the document.
• Lisa will do a loose comparison and then pass it over to Julie to look at for an obvious errors, then Julie will send an email to your group to review.
• Julie will add files and modify conf.py to enable a version selector, so that different versions of the documentation can be viewed (e.g. v3.0.0, master, development, etc.)
• Randy, have you had a chance to review the front page ( https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/index.html)? We had talked about you adding history that includes MATS. You can either comment here and Lisa or I will add it, or you can modify the .rst file directly - whatever you are comfortable with.
• The writing perspective does not seem to be consistent within the METexpress User’s Guide. Sections 1 - 3 seem to be in third person ("one",), which is consistent with the other METplus components’ User’s Guides; Sections 4 and 5 seems to be in second person ("you"). Examples below. Do we want to be consistent? If you would like Sections 4 and 5 modified to be in third person, Lisa would be happy to take on this task.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/apps.html Contour: Contour plots can be used in many ways. One can illustrate data with respect to height, as in plots seen at http://www.emc.ncep.noaa.gov/gmb/STATS_vsdb/, which have height on the y-axis and forecast hour (as in lead time) on the x-axis.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/installation.html Software: You must have docker, docker-compose, httpaswd, and jq installed. You should have a certificate installed in /etc/ssl/certs, although you can deploy a simple system on localhost without certificates for testing. A simple testing system can be deployed by answering yes to the question “Are you setting up a simple test environment?” in the configure program.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/dtcenter/METexpress/issues/1#issuecomment-708672737, or unsubscribe https://github.com/notifications/unsubscribe-auth/AGDVQPUYAU6XUB5NZ53LZSDSKYKPFANCNFSM4R6ESH7Q .

-- Randy Pierce

[jprestop]

Thanks, Randy! No apology is necessary. We've been kept plenty busy. I just thought I'd follow up on it. Regarding the third person perspective, will you be rewriting those sections? If so, do you plan to modify the .rst files directly in this branch or do you plan to send us updates? If not, would you like Lisa to take on the task of getting those sections in third person perspective?

[bonnystrong]

FYI, I noticed at https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/interface.html that the figure number in the section below is wrong. It should be Figure 2.1

2.1. Home Page

The METexpress home page is shown in Figure 2.2 https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/interface.html#image003. The home page has a button for each available app. Each app lets the user create certain types of plots for a certain type of data. The user must begin by selecting the app they want to use.

On Wed, Oct 14, 2020 at 3:34 PM jprestop notifications@github.com wrote:

Update on documentation:

• Lisa will add the Acknowledgement section that Bonny sent to me today.
• Lisa will update some images in the document.
• Lisa will do a loose comparison and then pass it over to Julie to look at for an obvious errors, then Julie will send an email to your group to review.
• Julie will add files and modify conf.py to enable a version selector, so that different versions of the documentation can be viewed (e.g. v3.0.0, master, development, etc.)
• Randy, have you had a chance to review the front page ( https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/index.html)? We had talked about you adding history that includes MATS. You can either comment here and Lisa or I will add it, or you can modify the .rst file directly - whatever you are comfortable with.
• The writing perspective does not seem to be consistent within the METexpress User’s Guide. Sections 1 - 3 seem to be in third person ("one",), which is consistent with the other METplus components’ User’s Guides; Sections 4 and 5 seems to be in second person ("you"). Examples below. Do we want to be consistent? If you would like Sections 4 and 5 modified to be in third person, Lisa would be happy to take on this task.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/apps.html Contour: Contour plots can be used in many ways. One can illustrate data with respect to height, as in plots seen at http://www.emc.ncep.noaa.gov/gmb/STATS_vsdb/, which have height on the y-axis and forecast hour (as in lead time) on the x-axis.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/installation.html Software: You must have docker, docker-compose, httpaswd, and jq installed. You should have a certificate installed in /etc/ssl/certs, although you can deploy a simple system on localhost without certificates for testing. A simple testing system can be deployed by answering yes to the question “Are you setting up a simple test environment?” in the configure program.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/dtcenter/METexpress/issues/1#issuecomment-708672737, or unsubscribe https://github.com/notifications/unsubscribe-auth/AG6HZOQFNL2RKSYUX3FRSCLSKYKPFANCNFSM4R6ESH7Q .

-- Bonny Strong NOAA ESRL/GSL and CIRA 303 497-3936

[jprestop]

Thanks for mentioning that, Bonny. That is exactly the sort of thing Lisa will be checking for before passing it along, so hopefully we'll catch all of those sorts of things, however, please feel free to continue to point out anything you find and we'll ensure those things are changed. Thanks!

[randytpierce]

I am modifying the rst file and I'll let you know when I finish. thanks, randy

On Wed, Oct 14, 2020 at 3:34 PM jprestop notifications@github.com wrote:

Update on documentation:

• Lisa will add the Acknowledgement section that Bonny sent to me today.
• Lisa will update some images in the document.
• Lisa will do a loose comparison and then pass it over to Julie to look at for an obvious errors, then Julie will send an email to your group to review.
• Julie will add files and modify conf.py to enable a version selector, so that different versions of the documentation can be viewed (e.g. v3.0.0, master, development, etc.)
• Randy, have you had a chance to review the front page ( https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/index.html)? We had talked about you adding history that includes MATS. You can either comment here and Lisa or I will add it, or you can modify the .rst file directly - whatever you are comfortable with.
• The writing perspective does not seem to be consistent within the METexpress User’s Guide. Sections 1 - 3 seem to be in third person ("one",), which is consistent with the other METplus components’ User’s Guides; Sections 4 and 5 seems to be in second person ("you"). Examples below. Do we want to be consistent? If you would like Sections 4 and 5 modified to be in third person, Lisa would be happy to take on this task.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/apps.html Contour: Contour plots can be used in many ways. One can illustrate data with respect to height, as in plots seen at http://www.emc.ncep.noaa.gov/gmb/STATS_vsdb/, which have height on the y-axis and forecast hour (as in lead time) on the x-axis.

https://ral.ucar.edu/staff/jpresto/work/METexpress_lisag/Users_Guide/installation.html Software: You must have docker, docker-compose, httpaswd, and jq installed. You should have a certificate installed in /etc/ssl/certs, although you can deploy a simple system on localhost without certificates for testing. A simple testing system can be deployed by answering yes to the question “Are you setting up a simple test environment?” in the configure program.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/dtcenter/METexpress/issues/1#issuecomment-708672737, or unsubscribe https://github.com/notifications/unsubscribe-auth/AGDVQPUYAU6XUB5NZ53LZSDSKYKPFANCNFSM4R6ESH7Q .

-- Randy Pierce

[jprestop]

Hi Randy and LIsa.

I just pushed some files up to this branch:

new file:   _static/pop_ver.js
new file:   _templates/footer.html
modified:   conf.py
modified:   index.rst

You should do a "git pull" to pull these changes into your local git repo before pushing your changes. Please let me know if you have any questions or problems. Thanks!

[jprestop]

Lisa has finished transitioning the METexpress documentation into Sphinx.

I believe we still need to have Randy add information about MATS to the front page at docs/index.rst. I believe we also still need to have Sections 4 and 5 rewritten in third person either by Randy or Lisa, if desired. Lisa is happy to work on it if you’d like, we just need to let her know if that is what you all would like. Can someone please follow up on how to proceed?

You can view the document here: https://ral.ucar.edu/staff/jpresto/work/METexpress_jpresto/index.html

We can submit a pull request now and you can make suggestions for changes in the pull request, or you can review the documentation at the link above, suggest changes, and we can make changes now and submit a pull request after. Which do you prefer?

[ksearight]

@jprestop ready for you to make public