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

[MarcSkovMadsen]

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

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

Let me try to navigate via the menu then

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

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

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

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.

[MarcSkovMadsen]

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.

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

[MarcSkovMadsen]

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.

[ceball]

@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):

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

[MarcSkovMadsen]

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]

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.

[MarcSkovMadsen]

I've added a feature request for a style guide for Panel as this would help create better help in modern editors/ IDEs and when using Sphinx.

#1042

[philippjfr]

The website has received a significant overhaul since this was posted and a lot of the items here were addressed. I'll close this but I'd encourage filing requests for specific improvements that you'd still like to see.