Add missing docstrings to all __init__.py files

[flohorovicic]

Originally this issue only said "Decide on general format of Readme files", but now it supersedes #281 and I am adding more details - @alexanderzimmerman 2020/04/07

During the GemPy retreat, we identified an issue that the purposes of the sub-folders within the gempy folder, e.g. "assets" and "addons", were unclear.

A solution we thought of was to put a README.md in each folder.

An alternative would be to document each sub-folder as a sub-package (which they technically are) and simply add docstrings to their __init__.py files.

[flohorovicic]

Suggestions for README.md files

Please check and comment @alexanderzimmerman

General comments

• place one in each subfolder of repository
• name: README.md
• markdown format (some info here: https://www.makeareadme.com)

Layout

README.md for folder

Folder content

(Short description for files in this folder)

Testing

(Details on testing, i.e.: files in this folder should have a corresponding test file; or files not tested, etc.)

Contribution guidelines

(Some information on contribution, i.e.: for core developers, for links to other projects, etc.)

For more information see (link to Contribution.md, soon to be implemented #287)

[agzimmerman]

I think that the "Testing" and "Contribution guidelines" sections are important for our top level README but not necessarily for every lower level README. What is most important is the "Folder content".

Also the original problem was that it was unclear how we were organizing "assets", "addons", and "utils". So as long as there is enough information to make this clear, I think it's good.

[alex-schaaf]

Yeah I agree that subfolder readme files should not contain any contribution guidelines. If relevant, they should only reference / link to the CONTRIBUTION.md located at the project top level

[flohorovicic]

I think it is important to see, in each Readme:

• are files in this folder part of the testing system
• am supposed to contribute here, or is this something for the "core" developers.

Not sure about the second point - as we expect technically everyone to contribute to all gempy parts?

[agzimmerman]

I think it is important to see, in each Readme:

• are files in this folder part of the testing system

I think that files that are particularly for the testing system should be in the test folder.

• am supposed to contribute here, or is this something for the "core" developers.

Not sure about the second point - as we expect technically everyone to contribute to all gempy parts?

I don't think that we should document this in distributed README's. If we want to direct people about where they should and should not contribute, then that should go into Contributing.md.

[agzimmerman]

@flohorovicic , I am not sure what is meant by "(Short description for files in this folder)" in the proposed template.

Maybe we are looking at this wrong.

The problem we identified in the retreat ( #281 ) was that the purpose of the different folders was unclear.

Putting more thought into this now, I think that we should view them as subpackages and ensure that every __init__.py file has a docstring. The docstring documents the purpose of the subpackage. What do @Leguark and @pytzcarraldo think?

[agzimmerman]

It's unclear to me why a separate issue was created for this discussion. There is no information at the issue #281. I'm going to close that one and rename this one.

[alex-schaaf]

Putting more thought into this now, I think that we should view them as subpackages and ensure that every init.py file has a docstring. The docstring documents the purpose of the subpackage.

Sounds like a good solution to me!