Instantiating Classes in bw2data, etc. - How to deal with this?

[michaelweinold]

Context: @cmutel moved functionality from bw2data into the new bw_projects library (cf. brightway-lca/brightway2-data#97). This now means that, for instance, it is currently impossible to find any documentation on the bw2data.delete_project(), since it is actually defined in a class of the bw_projects package and only instantiated in bw2data.

See also:

• Search Function returns limited Results #133

I understand that the documentation is not perfect, nor can it ever be the priority of the core Brightway development team. However, we have a good understanding of where users go when trying to understand or searching for Brightway functions:

The way key packages like bw2data take classes from other packages makes it very difficult to use the documentation and the source code. Using random cells from example notebooks that are floating around can not be the way we offer users information.

We should discuss:

• What the exact reasoning behind the moving-code-elsewhere was. Is this good coding practice? For instance, I don't see how a new package (bw_projects) is necessary from only:

Projects as separate subdirectories is not a useful concept for all databases or organizations.

• If this is good coding practice, how are other packages handling this?
• ...what can we do about it? Do I need to make changes in the way the API documentation is built? Do we need to change the source code?