search

earthobservations / wetterdienst

Open weather data for humans.
https://wetterdienst.readthedocs.io/
MIT License
349 stars 54 forks source link

Documentation has room for improvements #136

Closed larsrinn closed 3 years ago

larsrinn commented 4 years ago

Is your feature request related to a problem? Please describe. The documentation is incomplete and outdated. For example this page: https://wetterdienst.readthedocs.io/en/latest/pages/api.html#api-for-historical-weather-data references wetterdienst.collect_dwd_data, which is not existing anymore.

A lack of documentation makes it harder for new users to adopt to this library and may cause some people to turn it down. Wrong documentation is even worse than no documentation.

Describe the solution you'd like

Additional context

I was curious to test the various bits and pieces. If you're interested, I could open a PR where they're cobbled together on the weekend.

gutzbenj commented 4 years ago

Hey @larsrinn ,

thank you very much for the notice! You're absolutely right with your critics!

I'd be very happy with a PR, as I'm currently out of time to work on it myself!

Actually I also missed to document how to run the current code formatter which is

# Format code.
nox -s black

# Check format.
nox -s lint

This is important to get the Github Actions run successfully.

amotl commented 3 years ago

Dear Lars,

thanks for your thoughtful recommendations. We have been able to make some progress on some ends of what you were suggesting here. We will still be happy about anyone to improve the documentation further.

The documentation is incomplete and outdated. Wrong documentation is even worse than no documentation.

I hear you. We fixed it.

May I humbly ask you to review the current state of the documentation again and point out any other issues we still might have missed in this regard?

Add a quickstart page that basically just shows what is currently on the API-page.

Thanks. Now, we are trying to give a short but concise synopsis directly on the welcome page (Introduction/README.rst). Also, we added respective examples on how to use wetterdienst from the command line here.

More advanced stuff is still to be found on the API-page, which has also been cleaned up a bit.

Make use of of autodoc.

We just enabled that. Thanks!

Make use of sphinx-autodoc-typehints.

I didn't know about this one yet. Now, it is also enabled. Thanks again!

Make use of doctest.

I am a big fan of doctest. On the other hand, it often becomes tedious to maintain a whole test suite only made of doctests, so we focused on the pytest-based test harness for now. However, I see a fit for bringing this in for the very purpose you are requesting this here in order to have a verified API documentation which will never break even after the code changes.

With kind regards, Andreas.

amotl commented 3 years ago

Backlog

@larsrinn: I would like to collect some leftovers from your suggestions within this comment.

Use doctests

Make use of doctest in order to cover the examples and snippets outlined within the documentation from breaking. pytest can be configured to auto-run doctests as well, see Pytest integration with Doctest. On top of that, there's also sphinx.ext.doctest.

I have diverted that into #159.

Improve autodoc

Make use of of autodoc to create an API page automatically from the docstrings without any additional effort. To do that, don't document the the __init__ method of a class but instead the class itself - this seems pretty standard. For reference, pandas handles it the same way.

We configured to use docstrings from both class-level and __init__: https://github.com/earthobservations/wetterdienst/blob/e5d5b9a03374822327a6990b38f4e85b907f1143/docs/conf.py#L102-L103

  1. We still might want to move the main class documentation to the class-level where appropriate.
  2. I've just added some modules for now, see docs/pages/library/. We might want to continue on that and discuss whether we want to publish stuff for each and every bit of code or just for a curated subset.

iPython for Sphinx

The sphinxext.ipython_directive for Sphinx could be used to auto-create the output of a tutorial page (in contrast to pages with doctests, where you need to specify the expected output by hand).

@gutzbenj already added #148 the other day. Maybe he is lucky to get this working within one of the next iterations?

gutzbenj commented 3 years ago

Dear Andreas,

doctests

Using doctests in its full functionality we would have to take care not to use data that is updated on a daily basis to prevent have datetimes between two data releases. I'd be happy for now to just test that the code is running.

Improve autodoc

thanks for your effort once again! I agree with you that probably we should shift the whole class descriptions into one place which is the class itself instead of the init.

iPython for Sphinx

I played with that one but couldn't yet get output by it. Also the question is if this can be combine with extended doctests which I haven't figured out so far. I will do further investigations on this topic, as we should definitely get the output produced automatically.

gutzbenj commented 3 years ago

Dear @larsrinn ,

do you have any further suggestions for the improvement of the documentation? Otherwise I would close this Issue.

I guess we are only missing real doctests atm.

amotl commented 3 years ago

Dear Lars,

we have significantly improved the documentation following many of your suggestions and will be happy about another review.

With kind regards, Andreas.