Docs now built with sphinx directly and API reference refactored

[maximlt]

Main changes:

• nbsite is no longer the executable that builds the docs, instead it's done with sphinx directly. To make this change, I've had to move all the notebooks from ./examples to ./doc. This isn't a problem for the Param project as it doesn't have an examples command like Panel and other HoloViz projects. This change should make it easier to work on the docs and use tools like sphinx-autobuild.
• attempts to improve the API reference. I've played around with sphinx's autosummary extension, I'm not sure I like it entirely as you can't configure that much the autogenerated doc for each entry compared to what you can do with e.g. autoclass. It still feels like an improvement though!

Here are two ways to reference the API from the docs (thanks to this SO post)

param/doc/reference/param.md

Line 22 in 5d0cffb

of {py:class}`Parameterized` classes and instances.

param/doc/user_guide/Parameter_Types.ipynb

Line 65 in 5d0cffb

"- [`param.String`](param.String): String value, with optional regular expression (regex) constraints\n",

EDIT: I built the dev docs from this branch, see the new API page https://holoviz-dev.github.io/param/reference/index.html

@droumis do you mind reviewing this PR?

[maximlt]

Thanks for the review @droumis ! It's still not quite clear to me what's the best structure for the API reference of Param, it's a good experiment anyway and give us some insights on how we'll structure Panel's one.

Unfortunately I won't have time to complete this PR now so feel free to take it over if you have some bandwidth and interest in getting it in Param 2.0. Otherwise it can sit there as it's definitely not a blocker for the release.

[philippjfr]

I think this PR is a big improvement on what we had before so I'm going ahead and merging it. We also discussed this in our docs sync the other day and decided that manually curating overview pages is going to be the only sensible way forward but that we would likely try to add some automation to automate the process of listing all objects of a single type, e.g. for listing all Parameter subclasses, and for listing all methods/attributes of a specific class, e.g. for the Parameters namespace.

[droumis]

ok, I'm experimenting with ways to avoid the redirect and have a better tiered left nav, but I can finish later in another PR

[droumis]

Or, if you can wait until tomorrow to merge, I have some time later today

[philippjfr]

Sounds great, I'll wait.

[droumis]

I figured out how we can have the reference API section headings in the leftnav instead of the individual class pages. https://holoviz-dev.github.io/param/reference/index.html

Screen.Recording.2023-08-18.at.9.47.13.AM.mov

In order to have links in the leftnav, each section heading has to be a separate file, so I've broken them out into files that are now in doc/reference/param/. However, to get their contents aggregated on the same page as before, I used the 'include' directive to insert the content from each of the new section pages into a single param/index.md page. Additionally, to be listed in the leftnav, each page needs a title (e.g. '# title').. which screws up the include directive. To fix that, I used ":start-line: 2" for each include directive to skip over the title in the first line.

Additionally, the autosummary extension automatically adds its generated pages to the toc... so in order to suppress this, I installed a new plugin called sphinx-remove-toctrees. This should also speed up the docs build for bigger holoviz projects if we choose to implement it across packages. I've added it to the 'doc' list in pyproject.toml for now.

Lastly, I've renamed "Main objects" to "Parameterized objects", and I've moved the ParamOverrides class from this section into the "Parameter helpers" section. I was trying to decide whether to place it in "Parameter helpers" or "Parameterized helpers", but considering the functionality of ParamOverrides, it seems more related to the manipulation and management of parameters, rather than event handling or watchers.

[droumis]

ready to merge. We can iterate on the structure more later