-
-
Notifications
You must be signed in to change notification settings - Fork 108
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Adds docstrings to the core
module
#827
Adds docstrings to the core
module
#827
Conversation
Would you be willing to accept a larger PR in the style of what I have started here @maximlt or @philippjfr ? |
Recommending different APIs given what editors people use make me sad :( I think we'll have to discuss this more before committing to this. |
Strongly agree, I can see the issue with tab-completion but on balance I'm a strong -1 on recommending two separate APIs based on your editor. |
For this PR I will then
Would you be willing to look positively at reviewing and accepting a larger PR then? |
Sounds good and to be clear I won't object to adding some discussion about different APIs and usage patterns in the docs. Just not excited about recommending different APIs directly in the docstrings.
Absolutely. |
Just for the record. Besides better intellisense in editors, using |
I've added a reference example to the top, opening post and pushed the code. Feel free to comment on the code and guide me. It will be a lot of work to do and if you don't like it @maximlt and @philippjfr I would have wasted a lot of time. Thanks. |
I'm on a holidays today, I'll have a closer look at it later this week. What I can say from a quick glance is that it looks like a good start. A very important point imo is that you seem to be heading towards writing docstrings that are long enough to be part, or even entirely constitute, the reference gallery page of the documented plot. There shouldn't be two separate systems of documentation (docstring and reference gallery) to maintain at the same time, otherwise I wouldn't consider that as an extra burden on a documentation we already struggle to maintain. |
Thanks for your comments. I would say that Documentation in different places serves different purposes and is really, really needed for My opinion is that the Reference Gallery should have lots of different examples. I believe you cannot outsource to the user guide to show how to use some of the fundamental powers of hvPlot like I am not so worried about the docstrings in the |
I think it would be a mistake to try to have too much information in the
I feel your pain about the documentation and your desire to promote more hvPlot. I don't think that it's by stuffing more information in the reference gallery that this is going to work and improve the documentation, it is just going to make it even less maintainable in the future. For instance, giving you suggestion we should show
Yes, but to me really the keys to that are better cross-linking and better docs (for instance, a nice and short hvPlot tutorial that quickly demonstrates all you can do), not repeating the same information everywhere. Something that is of a higher priority in my opinion is the need to have a reference gallery that displays not only Bokeh plots but also Matplotlib and Plotly plots. We need a system to make that work and render in a nice way.
Which part of Pandas' documentation gives you this impression exactly? That page https://pandas.pydata.org/pandas-docs/stable/user_guide/visualization.html#chart-visualization? |
This https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.plot.line.html and similarly the other links I've referenced for
The Pandas link is actually populated by their docstring. Plotly knows that lots of examples are needed. It takes a long time before users have a mental model and can navigate. If you are new to plotting then you wont have a chance with |
Regarding Diataxis framework I also believe in it. But as I see it, it refers to written documentation for books/ web sites. My current belief is that tooltips and help in notebooks are a bit different because they are constrained. Users are looking for quick information. Reference for sure. But also a bit of the rest including "how-to". They are looking for something that will normally help them. |
Hi @maximlt I've
Let me know if you think this could get into the next release of hvPlot. Then I will continue the docstring work in a new PR. |
One note on signatures and docstrings. I can see some key parameters are not in the signature or docstring. Unless somewhere tells me otherwise (@maximlt , @philippjfr ) the guiding principles for me are
I say this because I can see for example the special |
Thanks @MarcSkovMadsen ! Excellent improvements to the docstrings! Merging as is. I think there are still some changes that are due to your auto-formatter, please the next time make sure you don't commit such changes, they're difficult to revert. The test file you have added will actually not run. All the test files are named "testthing.py" and not "test_thing.py", the former being what is picked up by pytest. I keep it anyway as ultimately I'd like to turn it into a script that would run during a doc build, I don't think it's necessary to run it part of the unit tests (and this single test takes 30 secs to run). |
Thanks @maximlt The docs are a tough process. There is a lot I have to learn and a lot we have to align on. I'm not done yet at all. But I am super motivated by the fact that I can get improvements into the next release and start to get feedback and see how it works out in practice. Thanks. |
This PR aims to add better docstring for users. It does this by providing more descriptive text, examples and reference links similar to the docstrings recently added to Panel.
I will try to stick to the reference example below.
As a user I would like to understand
As a developer or supporter on Discourse working on the specific plot it is very helpful to be able to find the Pandas
.plot
and backend references quickly.For beginners the docstring should contain just enough information to get a general idea of what this is and if it is the right plot to use. For more info they can head of to the reference documentation.
For super users the docstring should have just enough information to refresh your memory and be able to work. And we should be able to navigate without to much context switching. When you have to leave your editor or IDE there is a cost.
Many users (my self included) have not been educated abstractly (we might have concretely) in data visualization. I.e. we might not know the right terms, the right plot to use for the kind of data, not understand why we cannot make a bar plot from non-categorical data when that is normal for other frameworks to support etc. So the docs should help guide and share knowledge.