Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Please add more structure, search, navigation and content to Panel Documentation #833
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.
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
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 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.)
Yes and no.
Yes. In priciple the holoviews api documentation is the reference guide i'm looking for.
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. :-)
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.)
I can recall two issues we have with reference manual generation across holoviz projects: