Establish conventions for the Pyomo API

[whart222]

Summary

A formal description of the Pyomo API would help manage technical debt for maintenance of Pyomo.

Rationale

I've been thinking a bit about the Pyomo API as I consider strategies to replace kernels with C/C++ extensions. However, I've noted that Pyomo developers pull logic from deep in Pyomo's directory structure. For example, the identify_variables() function isn't included in pyomo.core, but needs to be pulled from pyomo.core.expr.visitor.

A clearer declaration of the Pyomo API would help manage technical debt in Pyomo. This seems timely given the maturation of pyomo.contrib capabilities, which will be treated as stable functionality in future releases.

Description

SciPy has a nice articulation of their API and associated conventions. I recommend that we consider something similar for Pyomo:

https://docs.scipy.org/doc/scipy/reference/

[blnicho]

@whart222 we should edit this to add a clear set of classes/methods/functions that we're going to consider the "Pyomo API" and add documentation and API tests for. It doesn't have to be perfect or complete in this issue but I think we need a starting point for what we consider the main API and how we will know when this issue is resolved.