Adjust use of GetDefaultOpenOptions in PlainText quickrecipes

[brugger1]

I was looking at the Python code example in PlainText file format section of the Getting Data into VisIt chapter and found what I that was incorrect code.

On further investigation, I found it was referencing a snippet of code from our test suite so it must work. The issue is that the function to get the file open options is GetDefaultFileOpenOptions, but the example code used GetDefaultOpenOptions. It turns out the test suite code defines a GetDefaultOpenOptions that calls GetDefaultFileOpenOptions. Someone viewing that example would never know that and if they tried to use the code it wouldn't work.

[markcmiller86]

I'm pretty sure I introduced that and there is a comment in plaintext.py above that definition...

#   
# Use this function with deepcopy to ensure we always start from a
# prestine default state for open options.
#
def GetDefaultOpenOptions():
    if not hasattr(GetDefaultOpenOptions, 'defaultOpenOptions'):
        GetDefaultOpenOptions.defaultOpenOptions = copy.deepcopy(GetDefaultFileOpenOptions("PlainText"))
    return copy.deepcopy(GetDefaultOpenOptions.defaultOpenOptions)

This is to ensure that each block of code starts from a fresh/clean copy of the options instead of having to constant re-define them from block to block.

Now, you've identified a big problem...the code appearing in the docs then doesn't look as it should. So, this can be corrected by first copying the method pointer, GetDefaultFileOpenOptions, to a local variable in the .py file and then overriding that method as below...

_getDefaultFileOpenOptions = GetDefaultFileOpenOptions
#
# Use this function to override GetDefaultFileOpenOptions with deepcopy to ensure
# we always start from a prestine default state for open options.
#
def GetDefaultFileOpenOptions(pluginName):
    assert(pluginName=='PlainText')
    if not hasattr(GetDefaultFileOpenOptions, 'defaultOpenOptions'):
        GetDefaultFileOpenOptions.defaultOpenOptions = copy.deepcopy(_getDefaultFileOpenOptions(pluginName))
    return copy.deepcopy(GetDefaultFileOpenOptions.defaultOpenOptions)

Then everywhere in the file replace GetDefaultOpenOptions() (which is misleading) to GetDefaultFileOpenOptions('PlainText') which is the code as it should appear. Note, I added an assertion in the above to enforce that it is always called that way.

This is some of the gymnastics involved in including code in our docs that actually also gets run and passes its testing. But, I think it is worth doing too. In this case each example block should stand on its own in the documentation and not have remnents having to do with undoing some of the effects from other blocks.

[JustinPrivitera]

Didn't this get addressed here: #19663

[JustinPrivitera]

I am wondering where that fix went

[markcmiller86]

It is committed on develop and the remarks you added do appear in the docs here, https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/data_into_visit/PlainTextFormat.html

That said, I much prefer the solution I proposed here because it results in the code blocks appearing exactly as they would and removes the need for any commentary to explain it.

Maybe I should take this one?

[JustinPrivitera]

What is the stable version of the docs? How do you get there?

[markcmiller86]

@JustinPrivitera can you go to readthedocs.org and register for a free account there? Then, I can add you to the VisIt documentation generation project.

[JustinPrivitera]

ok will do.

The URL that Eric sent with the bad docs is from stable, the develop docs are fine. What are the "stable" docs and how do you get to them? How would users get to them?

[JustinPrivitera]

I made an account with the username privitera1

[markcmiller86]

I sent you an invite for the VisIt project there.

I have no idea what stable on ReadTheDocs actually means. It don't see any way to tell RTD what branch stable should be associated with.

[JustinPrivitera]

It is committed on develop and the remarks you added do appear in the docs here, https://visit-sphinx-github-user-manual.readthedocs.io/en/develop/data_into_visit/PlainTextFormat.html

That said, I much prefer the solution I proposed here because it results in the code blocks appearing exactly as they would and removes the need for any commentary to explain it.

Maybe I should take this one?

So regardless of it we go with your solution (which we probably should) or not, the problem will still remain that your fix will go on develop, and stable will stay what it is. I don't understand why stable exists nor how you get there without manually choosing it when looking at the docs. Perhaps @brugger1 can shed some light.

[JustinPrivitera]

I joined the visit project on read the docs; thanks for the invite. It looks like I can hide stable if I choose:

3.4.1 seems to also use stable:

This is all very mysterious.