Approach to Python CLI documentation

[markcmiller86]

Types of CLI Documentation

• API documentation
  • in functions.rst
  • The facts mam, just the facts
  • Associated with a specific CLI method
  • Function args, default values, return values
  • Some minimal description prose
  • Short example code snipits (almost all of which currently involve multiple CLI method)
  • appears in help() when running Python interpreter and in on-line manual
  • pictures ok but won't appear in help() output in Python interpreter nor cause issues with help() output either
• Recipes
  • in quickrecipes.rst
  • Longer/more example code snipits
  • Not bound to any specific CLI method
  • Almost always involve multiple CLI methods
  • Lengthier description prose, sections, sub-sections, cross-references, pictures
  • Only appears in on-line manual
  • Where API docs explain how to do an image annotation, Recipes describe how to use that feature to do perform some commonly desired user task like add a logo image or an UNCLASSIFIED banner.
• Tutorials
  • Describe how to use VisIt for a common whole-workflow analysis task
  • Or, full VisIt CLI apps like visit --diff
  • Even more fully developed code blocks, prose, etc. and longer narrative than either of the above
  • Typically also includes data files needed as part of the tutorial.

Requirements for CLI Documentation

We also have some requirements for the CLI documentation (only some of which -- those checked -- are met by current approach):

• [x] Be easily searchable from Python interpreter, on-line and stand-alone
• [x] Be cross-reference searchable (e.g. searching for legend -- or regex thereof -- turns up GetAnnotationObject()) in Python interpreter, on-line and stand-alone
• [x] Allow developers to compose in Sphinx/reST
• [x] Autogen python docstrings from Sphinx/reST
• [ ] Where some CLI functionality gets documented is clear (e.g functions.rst or quickrecipes.rst or elsewhere)
• [ ] Follow adopted Python conventions for docstrings (PEP257 and PEP287)
• [ ] Use one of the adopted formats for Python docstrings (reST, Google, Scipy, Epytext)
  • Note: the word format here refers to the ascii arrangement displayed by help() from within the interpreter
  • reST is the obvious choice since we're already using it in Sphinx

Observations of Current Approach

• Duplication of content
  • A look at content of quickrecipes.rst is that IMHO ~90% of it duplicates content already in functions.rst. There may be slight variations but not IMHO significant. I am inclined to believe that the rationale for a majority of this duplication was to satisfy one of the other requirements, likely ease of searching. Unfortunately, with the content in quickrecipes.rst, that satisfies only an on-line search and not a search from Python interpreter. For the latter, we really need to have all that documentation in the one place chosen to source both on-line and interpreter docs (e.g. functions.rst) and to add some additional CLI methods like visit_apropos to make it easily findable.
  • The cases where quickrecipes.rst content is unique have IMHO mostly to do with sub-object classes in the CLI (e.g. legend objects returned from GetAnnotationObject(), SIL objects, Query return objects -- though that is NOT actually documented there). OTOH, documentation of a given CLI method essentially just re-describes whats already in functions.rst. Why aren't these sub-objects documented in attributes.rst where all the attribute objects are documented?
• Ambiguous where content goes
  • To add documentation regarding for example GetQueryOutput() do all developers understand where that goes?
• Is there really any harm in having help() in python interp. pour out all the documentation we have on that method including stuff we are inclined to associate with a quick recipe (see below for an example of just that)?

Some steps forward

• We need a better CLI method for getting help based on searching rather than knowing the function name ahead of time. That is true regardless of anything else here. In other words, we need something that truly searches for stuff using string matching.
• We need to ensure cross-reference searching on-line docs "does the right thing". This may involve finding the right Sphinx knobs to turn, explicitly adding xrefs to our existing .rst files so that existing search funtionality behaves as expected or something else. Searching there for legend for example should have the effect of returning results which include GetAnnotationObject(). In fact, if the code snipit associated with that function in functions.rst had included a few lines demonstrating legends, indeed an on-line (or interpreter) search would have returned that part of the CLI manual.
• To be honest, default search behavior on RTD for CLI functionality is horrendously bad!!. Search there for GetAnnot. I would expect a lot of hits. Instead, I get nothing. I then tried getannotationobject. That also fails to find anything. If I type GetAnnotationObject, then I get a couple of hits. This means I have to know what I am searching for including the correct case before I can find it. We need to discover what Sphinx and/or RTD knobs to fiddle with to do partial word and case-insensitive searches.
• Note: the two steps above would IMHO go a long way to completely removing any need for separate functions.rst and quickrecipes.rst
• We should add some logic to functions_to_method_doc.py to produce docstrings that conform to Python standards as well as address #5006 and #5005
• We should opt to minimize content in quickrecipes.rst by avoiding duplication of functions.rst and document there only stuff that doesn't have a natural/strong association with a specific CLI function or is a known common usage pattern worth documenting in its own right.
• We haven't discussed attributes.rst but if we renamed this objects.rst then it could include documentation on all attribute objects and also all CLI method sub-objects like legends, SILs, query outputs, etc. It would be natural there to talk about a legends object. In fact, that object is a LegendAttributeObject. Turns out that isn't documented in attributes.rst. In fact, I found 33 missing objects and added them to #3602

Example of help(GetAnnotationObject) including quickrecipe.rst content

Help on built-in function GetAnnotationObject in module visit:

GetAnnotationObject(...)
    GetAnnotationObject

    Synopsis:

    GetAnnotationObject(string) -> Annotation object

    Arguments:

    string
        The name of the annotation object as returned by GetAnnotationObjectNames.

    Returns:

        GetAnnotationObject returns a reference to an annotation object that was
        created using the CreateAnnotationObject function.

    Description:

    GetAnnotationObject returns a reference to an annotation object that was
    created using the CreateAnnotationObject function. The string
    argument specifies the name of the desired annotation object. It must be
    one of the names returned by GetAnnotationObjectNames. This function is not
    currently necessary unless the annotation object that you used to create an
    annotation has gone out of scope and you need to create another reference
    to the object to set its properties. Also note that although this function
    will apparently also accept an integer index, that mode of access is not
    reliably and should be avoided.

    Adding annotations to your visualization improve the quality of the
    final visualization in that you can refine the colors that you use, add
    logos, or highlight features of interest in your plots. This section
    provides some recipes for creating annotations using scripting.

    Example:

    #% visit -cli
    OpenDatabase("/usr/gapps/visit/data/wave.visit")
    AddPlot("Pseudocolor", "pressure")
    DrawPlots()
    a = CreateAnnotationObject("TimeSlider")
    GetAnnotationObjectNames()
    ["plot0000", "TimeSlider1"]
    ref = GetAnnotationObject("TimeSlider1")
    print(ref)

    Using gradient background colors
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    VisIt’s default white background is not necessarily the best looking
    background color for presentations. Adding a gradient background under
    your plots is an easy way to add a small professional touch to your
    visualizations. VisIt provides a few different styles of gradient
    background: radial, top to bottom, bottom to top, left to right, and
    right to left. The gradient style is set using the
    *gradientBackgroundStyle* member of the AnnotationAttributes object. The
    before and after results are shown in Figure 1

      # Set a blue/black, radial, gradient background.
      a = AnnotationAttributes()
      a.backgroundMode = a.Gradient
      a.gradientBackgroundStyle = a.Radial
      a.gradientColor1 = (0,0,255,255) # Blue
      a.gradientColor2 = (0,0,0,255) # Black
      SetAnnotationAttributes(a)

    Adding a banner
    ~~~~~~~~~~~~~~~
    Banners are useful for providing titles for a visualization or for
    marking its content (see Figure 2) To add an "Unclassified"
    banner to a visualization, use the following bit of Python code:

      # Create a text object that we’ll use to indicate that our
      # visualization is unclassified.
      banner = CreateAnnotationObject("Text2D")
      banner.text = "Unclassified"
      banner.position = (0.37, 0.95)
      banner.fontBold = 1
      # print the attributes that you can set in the banner object.
      print banner

    Adding a time slider
    ~~~~~~~~~~~~~~~~~~~~

    Time sliders are important annotations for movies since they convey how
    much progress an animation has made as well as how many more frames have
    yet to be seen. The time slider is also important for showing the
    simulation time as the animation progresses so users can get a sense of
    when in the simulation important events occur. VisIt’s time slider
    annotation object is shown in Figure 3.
      # Add a time slider in the lower left corner
      slider = CreateAnnotationObject("TimeSlider")
      slider.height = 0.07
      # Print the options that are available in the time slider object
      print slider

    Adding a logo
    ~~~~~~~~~~~~~

    Adding a logo to a visualization is an important part of project
    identification for movies and other visualizations created with VisIt.
    If you have a logo image file stored in TIFF, JPEG, BMP, or PPM format
    then you can use it with VisIt as an image annotation (see Figure 4).
    Note that this approach can
    also be used to insert images of graphs, plots, portraits, diagrams, or
    any other form of image data into a visualization.

      # Incorporate LLNL logo image (llnl.jpeg) as an annotation
      image = CreateAnnotationObject("Image")
      image.image = "llnl.jpeg"
      image.position = (0.02, 0.02)
      # Print the other image annotation options
      print image

[markcmiller86]

So, after a couple of hours of search for what I thought would be controls on Sphinx/RTD searching features, I discovered that there are special syntaxes to perform partial match searches. I plan on adding a top-level link to this search info so that user's can easily find it.

[markcmiller86]

I've tried testing the special syntaxes referenced in previous comment. There are some things I honestly cannot confirm are working as advertised. I've filed an issue ticket

[biagas]

Would like to again state my case for keeping quickrecipes: it is good to have simple examples of things you may not know how to search for.

Yes, if you know exactly what you are looking for, a better search engine that finds your example in functions serves that purpose.

However, I often learn unexpected things by perusing simple examples like found in quickrecipes. Something I wasn't necessarily searching for, but useful nonetheless. I would never peruse something so lengthy as our functions documentation. I really only look at it if I know exactly what I need. In light of that, I am opposed to reducing content in quickrecipes.

[markcmiller86]

Would like to again state my case for keeping quickrecipes: it is good to have simple examples of things you may not know how to search for.

I wanna keep the content (that isn't duplicating content elsewhere). I am advocating for a different (IMHO better) way to handle it.

Yes, if you know exactly what you are looking for, a better search engine that finds your example in functions serves that purpose.

Both of the above statements allude to the impact of search in the decision to structure the docs as they are. That all tells me the root requirement is improved search...not introducing a new place to duplicate content so a usere has more chances of stubmling into it.

However, I often learn unexpected things by perusing simple examples like found in quickrecipes. Something I wasn't necessarily searching for, but useful nonetheless. I would never peruse something so lengthy as our functions documentation. I really only look at it if I know exactly what I need. In light of that, I am opposed to reducing content in quickrecipes

IMHO...the above perspectives suggest some key issues to be solved (did you disagree with any of the requirements above) with the way our CLI docs are structured and that some changes are needed. While the existence of quickrecipes.rst may address some, I think it introduces other issues and I think there is a better solution.

[markcmiller86]

Does anyone on @visit-dav/visit-developers know if/how we host our docs on closed systems? Do we serve them from a URL of some kind? Do users just browse them via file:// protocol? Have we decided or still working on this? The answer impacts whether a client-side search is more useful way to go.

[brugger1]

We don’t host them anywhere on the closed systems.

[markcmiller86]

We don’t host them anywhere on the closed systems.

Hmm...but we still enable users to get to them via GUI Help correct? I mean, that now launches a browser on the manuals, correct?

[brugger1]

Yes, they are in the GUI help and now that launches a browser on the manuals.

[markcmiller86]

Yes, they are in the GUI help and now that launches a browser on the manuals.

Just curious...do we know how search works under those conditions (e.g. file:// browsing) ? I am guessing it doesn't work at all or maybe very poorly but don't know for sure. There appears to be some attempt at providing some kind of client-side search but when I try it on static build it just enters an endless Searching... mode.

[cyrush]

I do think search works, there may be a step as part of the build that generates an index that is used?

That said, I personally haven't been very successful with sphinx searching, and I rely on the outline and hunt around. Even for large docs. It can't read your mind (or restated: it doesn't have feedback to discover the most useful common searches) like google.

I don't think the search issue is one we can really make a dent in, or solve by training our users. They aren't going to rely on search if they have a similar experience to mine.

I understand the maintenance burden related to duplication, but several projects provide quick recipes style docs to help get folks going with common use cases. It also provides hope and an expectation that a user should be able to wield these snippets without much mental anguish.

I guess I am not sure what the proposal is, is it to pack quick recipes style info into another place and extract it magically?

As some one who works on multiple projects - the more visit specific sphinx magic exists, the higher the context switching cost for me to contribute is.