G2G Installation Guide Issues

[kathys]

From our prestigious colleague, Scott L., a few errors he found in the document distributed with G2G in this section:

https://www.ssec.wisc.edu/software/geo2grid/utilscripts.html

---

Number lists aren't consecutive, under 8.1, you have 8.6.1 & 8.6.2, and then 8.2, then 8.6.1 and 8.6.2 again (and then 8.2.3, 8.2.4, ....)

8.6.1 is under 8.3 as well. In Section 8.3 there is also talk about Geo2Grid version 2.3, and it's 1.0.1, I think.

Then under 8.5 there are two 8. labels.

[djhoese]

So I figured out the issue, but don't have any great solutions yet. I've filed a bug with the sphinx-argparse project here, but I'm not sure there is an easy solution there either.

The main problem is that we have a single documentation page with multiple scripts being documented. All of those arguments sections have the same section names ("Positional Arguments" and "Named Arguments"). Sphinx sees these as all the same section and only indexes them once. So the weird numbering is actually that these arguments sections are all using the same section number of the last arguments section.

[djhoese]

I found a hacky solution to this that required editing the sphinx-argparse library. Another solution would be to split this single utility script page into multiple pages with a single "table of contents" page. I'm not sure we should jump to that as a solution quite yet.

[djhoese]

Just an update that this is still an issue even after all of the changes made to the documentation to support Polar2Grid and Geo2Grid in the same set of documentation. I'm still not sure on how I want to handle it as it would require a hack in the sphinx-argparse library which is now under new maintainership.

[djhoese]

This issue is not easy to solve and I have not gotten any good responses from the upstream third-party package used to generate these Positional Argument sections. It will require a decent debugging session to really come up with a non-breaking fix for the upstream package. Moving this to G2G 1.2 milestone in hopes that we pretend to have time to look into this.