Skip to content
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

Please add more structure, search, navigation and content to Panel Documentation #833

Open
MarcSkovMadsen opened this issue Dec 2, 2019 · 5 comments
Labels

Comments

@MarcSkovMadsen
Copy link

@MarcSkovMadsen MarcSkovMadsen commented Dec 2, 2019

I have been investing a lot of time to get up to speed with Panel over the last 3 weeks because it seems so powerfull.

But there is a lot of friction to getting started. One friction point is the documentation.

For example lets assume i'm a newbie and want to do a simple thing like learning about how to add markdown to my app.

If I use the search functionality at panel.pyviz.org i get no help

image

I've created a seperate feature request on improving the search functionality at #832.

Let me try to navigate via the menu then

image

Let me see. Where should I start? Let's start with the "Getting Started". No there is nothing on Markdown according to CTRL+f

image

What about the user guide then? Wow there is a lot of possibilities? Where should I start then?

image

I was lucky :-) On the components page there is something

image

But the example is not focused on markdown and it does not tell me much. I would like something more structured like what is normal in documents structured by Sphinx and a Read the Docs theme.

image

@MarcSkovMadsen

This comment has been minimized.

Copy link
Author

@MarcSkovMadsen MarcSkovMadsen commented Dec 2, 2019

Another example is the hidden reference guide.

I am actually looking for the reference guide. But I cannot find it via the Navigation.

But after some time I find out that the reference guide is just called reference gallery. I think that is confusing.

I go to a Reference Gallery to get inspiration on how to use the technology and how to put it together. But my expectations are that its not specific with all details and it takes time to consume and understand.

Normally I refer to a Reference Guide if I wan' to see specific, on the point information like which input parameters are available or how they should be used.

Please rename Reference Gallery to Reference Guide.

And by the way the Reference Gallery is great and contains a lot of the information I need. I just personally like the Sphinx/ Read the Docs format better.

image

Then we just need the markdown to be able to render code blocks as well :-) See #391

@MarcSkovMadsen

This comment has been minimized.

Copy link
Author

@MarcSkovMadsen MarcSkovMadsen commented Dec 2, 2019

Please note I write these thinks because I think that Panel could be so great and I can so so much effort has already been put into it and the HoloViews/ Bokeh ecosystem that it leverages. And thanks for that.

But it's not easy to get started and build a nice looking multipage analytics app.

@MarcSkovMadsen MarcSkovMadsen changed the title Please add more structure, search, navigation and content of Panel Documentation Please add more structure, search, navigation and content to Panel Documentation Dec 2, 2019
@ceball

This comment has been minimized.

Copy link
Member

@ceball ceball commented Dec 2, 2019

@MarcSkovMadsen I think one thing you're asking for is a 'reference manual' (or API documentation) - is that right? E.g. like this (from holoviews):

api

(Ignoring that the generated reference manual for holoviews and other holoviz projects is currently a bit ugly/awkward in various ways.)

@MarcSkovMadsen

This comment has been minimized.

Copy link
Author

@MarcSkovMadsen MarcSkovMadsen commented Dec 2, 2019

Hi @ceball

Yes and no.

Yes. In priciple the holoviews api documentation is the reference guide i'm looking for.
No. I don't wan't something similar to the holoviews api documentation. It's difficult to understand the structure of and to read. Maybe not after having spend the time with it. But it could scare of newbies. Compare to the Streamlit documentation. It's not going to scare people off.

And Read the Docs format is so well know and easy to read. Why not use it?

Please note this is written in a positive spirit of wanting to improve things. :-)

@ceball

This comment has been minimized.

Copy link
Member

@ceball ceball commented Dec 2, 2019

Yes, thanks, your comments/issues are valuable - please keep making them. (For background, we're aware of many of these kinds of issues, but finding time to address them is always the problem. Some problems are historical and even newer projects like panel have inherited them because we've had to optimize for maintainer time, to allow a small number of people to maintain multiple projects.)

And Read the Docs format is so well know and easy to read. Why not use it?

I can recall two issues we have with reference manual generation across holoviz projects:

  1. We need to improve handling of Parameters in auto-generated documentation. We can't just "use readthedocs" (actually the tools underlying it) without some customization because the most important items to document (Parameters) would not appear.
  2. We've never agreed to use one of the standard docstring formats (I think), e.g. numpy style. And we don't have consistent docstring style within/across projects.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.