Possibilities to improve documentation

[RecentConvert]

Huge fan of this work! I use Pyomo on multiple, customer-facing projects. @jsiirola asked that I keep track of opportunities to improve the Pyomo documentation. This is not meant to be an exhaustive list, but here's what I have so far:

Items to add

1. Add a section on how to create subsets and work with subsets. There are several good examples on Stackoverflow, one of which I found very useful and would quickly provide a code snippet for the documentation page.
2. Add a section on shorthand notation, which is really great to use btw. Two items of note here would be: (i) the @ notation for constraints, disjuncts, etc.; and (ii) the "index flatten" notation to succinctly replace all indices separately. An example of "index flatten" notation on a multi-indexed var:
   return 1 == sum(m.Start_Indicator[_] for _ in m.S[o])
3. Add a subsection on mutable parameters in the Parameters section. Include why mutable parameters are useful and an example of their use.
4. Add a subsection (perhaps in Pyomo Overview) on Pyomo imports, how to avoid using * imports, and make the distinction about how pyomo.environ technically pulls from multiple imports (when using @ notation) and is therefore sufficient to run a typical model without the need for pyomo.opt or others. Something like, "For typical users, pyomo.environ is fine" would be helpful in this case. It might be handy to link to other sections from this subsection for non-typical use cases, such as the different parts of Modeling Extensions, so the user can get a better feel for what is typical.
5. Consider implementing the following standard throughout all examples in the docs: import pyomo.environ as pyo. Introduce this notation in the subsection on Pyomo imports.
6. Add a section on a few specific python objects and their use in Pyomo, again targeting the typical use case. How to use the typical types of python objects (e.g., dictionaries, lists, sets, etc.) to create sets, vars, etc., and when to use each type of object. While these topics are currently sprinkled throughout, I think a section up front would be helpful, perhaps with the subsection on imports mentioned above. The Pyomo cookbook slides are good examples of what I'm thinking and perhaps portions could be lifted straight into the documentation.

Items to remove

7. Remove abstract models and all examples of their use. Currently, the decision to model as abstract or concrete is confusing, despite that the latter appears to provide greater functionality for modeling extensions and is therefore the superior paradigm. While the documentation explains certain differences, there doesn't appear to be a clear case for choosing one paradigm or the other aside from personal preference, so feel free to choose for the user and reduce confusion.

Items to revise

8. Sets -> Sparse Index Sets -> Sparse Index Sets Example: The language around this text to be misleading: "For many network flow applications, it might be better to declare the arcs using..." My understanding of within is simply for the use of error-checking, and I think this is open to misinterpretation.
9. Solving Pyomo Models: consider adding a reference list of the various arguments to the solve command, as is done in the subsections in Pyomo Modeling Components. A few I frequently use are tee=true, load_solutions, and options_string. Also, add text and an example to explain how to extract model results if the solution is suboptimal (e.g., time limit is reached, etc.). Perhaps the subsections under Working with Pyomo Models should be merged into this section.
10. pprint() is super useful. Consider making this highly visible somewhere.
11. General comment 1: frequently, some part of a section/subsection can be selected from the navigation menu on the left, and on doing so the page jumps to a header and a single line of text. This is a good example of what I mean. Navigation could be simplified by removing the section headers here and elsewhere, and thus would save headers for entire subsections within text when necessary.
12. General comment 2: there are entire sections of methods and lots of function arguments introduced in the Library Reference that aren't properly introduced in the documentation. This leads me to visit Stackoverflow a bunch when I might not need to.
13. General comment 3: the Developer Reference doesn't seem to serve a purpose. For instance, the discussion of Pyomo Expressions - the only material presented in this section - could simply be moved to Advanced Topics.

I hope this is helpful, and thanks again for this great work!