Closed larsrinn closed 3 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.
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.
@larsrinn: I would like to collect some leftovers from your suggestions within this comment.
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.
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
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.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?
Dear Andreas,
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.
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.
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.
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.
Dear Lars,
we have significantly improved the documentation following many of your suggestions and will be happy about another review.
With kind regards, Andreas.
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
__init__
method of a class but instead the class itself - this seems pretty standard. For reference, pandas handles it the same wayAdditional context
ipython
directive for sphinx: https://ipython.org/ipython-doc/3/api/generated/IPython.sphinxext.ipython_directive.html 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).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.