docstrings

[castelao]

I noticed a lack of documentation within your code. I'm guessing that your vision is to use it as a full application, i.e. load the configuration and run it, that's it. But other users might be interested in using it as a library, maybe just components of it, and build further other applications on top of it. Also, anyone interested in contributing to your package would appreciate some API documentation to save their time in understanding what is going on.

I suggest at least:

• The a one-line big picture
• A longer explanation is very helpful when there are assumptions and constraints for your implementation. Not always needed
• Inputs, pointing the expected data type, few words description, and if pertinent the units
• Output, same above
• If motivated, an example. Sometimes it is easier to understand with examples

Are you familiar with numpydoc? That's one way of doing it.

[pnsaevik]

Yeah, I can see your point. You're right about my thinking, but your arguments are valid as well.

In this project I'm trying to adhere to semantic versioning and not make breaking changes to the public interface. That's partially why I was reluctant to supplying public documentation to the modules and methods, which I wanted to be open to change. My thought was that the config file is the public interface and that's it.

But it is certainly possible to supply some documentation of the code structure while explicitly stating which parts are experimental and prone to change. This is done also in mature libraries like xarray. I'll put some thought into it, create a documentation draft and ask for your response. I'll do the work in a separate branch and publish the branch on readthedocs.io, so that the formatted end result is possible to inspect.

[castelao]

Make sense to me. I mentioned somewhere else, it might be useful for your case to use __all__ to control what to expose.

Let's close this issue and move all the related discussions to #24?