Docs now built with sphinx directly and API reference refactored

.gitignore

@@ -11,15 +11,16 @@
 *.lock
 .ipynb_checkpoints
 .vscode
-data.pickle
 dist/
 .venv/
 
 # Docs
 builtdocs/
 jupyter_execute/
-doc/user_guide/*.ipynb
 doc/Reference_Manual/
+doc/user_guide/data.pickle
+doc/user_guide/output.csv
+doc/reference/generated
 
 # Unit test / Coverage report
 .coverage

README.md

@@ -8,7 +8,7 @@
 | Latest release | [![Github release](https://img.shields.io/github/release/holoviz/param.svg?label=tag&colorB=11ccbb)](https://github.com/holoviz/param/releases) [![PyPI version](https://img.shields.io/pypi/v/param.svg?colorB=cc77dd)](https://pypi.python.org/pypi/param) [![param version](https://img.shields.io/conda/v/pyviz/param.svg?colorB=4488ff&style=flat)](https://anaconda.org/pyviz/param) [![conda-forge version](https://img.shields.io/conda/v/conda-forge/param.svg?label=conda%7Cconda-forge&colorB=4488ff)](https://anaconda.org/conda-forge/param) [![defaults version](https://img.shields.io/conda/v/anaconda/param.svg?label=conda%7Cdefaults&style=flat&colorB=4488ff)](https://anaconda.org/anaconda/param) |
 | Python | [![Python support](https://img.shields.io/pypi/pyversions/param.svg)](https://pypi.org/project/param/)
 | Docs | [![gh-pages](https://img.shields.io/github/last-commit/holoviz/param/gh-pages.svg)](https://github.com/holoviz/param/tree/gh-pages) [![site](https://img.shields.io/website-up-down-green-red/https/param.holoviz.org.svg)](https://param.holoviz.org) |
-| Binder | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/holoviz/param/main?labpath=examples) |
+| Binder | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/holoviz/param/main?labpath=doc) |
 | Support | [![Discourse](https://img.shields.io/discourse/status?server=https%3A%2F%2Fdiscourse.holoviz.org)](https://discourse.holoviz.org/) |
 
 Param is a library providing Parameters: Python attributes extended to have features such as type and range checking, dynamically generated values, documentation strings, default values, etc., each of which is inherited from parent classes if not specified in a subclass.

examples/Promo.ipynb → doc/Promo.ipynb

@@ -361,13 +361,13 @@
     "\n",
     "<table>\n",
     "<tr style=\"background-color:transparent\">\n",
-    "    <td> <a href=\"https://panel.pyviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/panel.png\"/></a></td>\n",
-    "    <td> <a href=\"https://hvplot.pyviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/hvplot.png\"/></a></td>\n",
+    "    <td> <a href=\"https://panel.holoviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/panel.png\"/></a></td>\n",
+    "    <td> <a href=\"https://hvplot.holoviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/hvplot.png\"/></a></td>\n",
     "    <td> <a href=\"https://holoviews.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/holoviews.png\"/></a></td>\n",
-    "    <td> <a href=\"http://geoviews.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/geoviews.png\"/></a></td>\n",
-    "    <td> <a href=\"http://datashader.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/datashader.png\"/></a></td>\n",
-    "    <td> <a href=\"https://param.pyviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/param.png\"/></a></td>\n",
-    "    <td> <a href=\"https://colorcet.pyviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/colorcet.png\"/></a></td>\n",
+    "    <td> <a href=\"https://geoviews.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/geoviews.png\"/></a></td>\n",
+    "    <td> <a href=\"https://datashader.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/datashader.png\"/></a></td>\n",
+    "    <td> <a href=\"https://param.holoviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/param.png\"/></a></td>\n",
+    "    <td> <a href=\"https://colorcet.holoviz.org\"><img style=\"height:100px;margin-right:1em;margin-left: 1em\" src=\"https://holoviz.org/assets/colorcet.png\"/></a></td>\n",
     "</tr>\n",
     "</table>"
    ]

doc/about.md

@@ -2,8 +2,8 @@
 
 Param is completely open source, available under a [BSD license](https://github.com/holoviz/param/blob/main/LICENSE.txt), freely for both commercial and non-commercial use. Param was originally developed at the University of Texas at Austin and the University of Edinburgh with funding from the US National Institutes of Health grant 1R01-MH66991. Param is now maintained by [Anaconda Inc.](https://anaconda.com) and by community contributors.
 
-Param is maintained as part of the [HoloViz](https://holoviz.org) family of tools. The [holoviz.org](https://holoviz.org) website shows how to use Param together with other libraries to solve complex problems, with detailed tutorials and examples. Each of the HoloViz tools builds on Param, as do many of the example projects at [examples.pyviz.org](https://examples.pyviz.org).
+Param is maintained as part of the [HoloViz](https://holoviz.org) family of tools. The [holoviz.org](https://holoviz.org) website shows how to use Param together with other libraries to solve complex problems, with detailed tutorials and examples. Each of the HoloViz tools builds on Param, as do many of the example projects at [examples.holoviz.org](https://examples.holoviz.org).
 
-If you have any questions or usage issues visit the [Param Discourse site](https://discourse.holoviz.org/c/param), and if you want to report bugs or request new features, first see if it's already in our list of [open issues](https://github.com/holoviz/param/issues) and then add to the issue or open a new one if needed.
+If you have any questions or usage issues visit the [Param Discourse forum](https://discourse.holoviz.org/c/param), and if you want to report bugs or request new features, first see if it's already in our list of [open issues](https://github.com/holoviz/param/issues) and then add to the issue or open a new one if needed.
 
 If you like Param and have built something you want to share, tweet a link or screenshot of your latest creation at [@HoloViz_org](https://twitter.com/HoloViz_org). Thanks!

doc/comparisons.md

@@ -1,8 +1,8 @@
 # Comparison to other approaches
 
-Param was first developed in 2003 for Python 2.1 as part of a long-running brain simulation [project](https://topographica.org), and was made into a separate package on [Github](https://github.com/holoviz/param/graphs/contributors) in 2012.  In the interim a variety of other libraries solving some of the same problems have been developed, including:
+Param was first developed in 2003 for Python 2.1 as part of a long-running brain simulation [project](http://ioam.github.io/topographica), and was made into a separate package on [Github](https://github.com/holoviz/param/graphs/contributors) in 2012.  In the interim a variety of other libraries solving some of the same problems have been developed, including:
 
-- [Traits](http://code.enthought.com/projects/traits)
+- [Traits](https://github.com/enthought/traits)
 - [Traitlets](https://github.com/ipython/traitlets)
 - [attrs](https://github.com/python-attrs/attrs) (with optional [attrs-strict](https://github.com/bloomberg/attrs-strict))
 - [Django models](https://docs.djangoproject.com/en/3.1/topics/db/models)

doc/conf.py

@@ -7,9 +7,10 @@
 
 from nbsite.shared_conf import *  # noqa
 
-project = u'param'
-authors = u'HoloViz developers'
-copyright = u'2003-2022 ' + authors
+project = 'param'
+authors = 'HoloViz developers'
+copyright_years['start_year'] = '2003'  # noqa
+copyright = copyright_fmt.format(**copyright_years)  # noqa
 description = 'Declarative Python programming using Parameters'
 
 version = release = base_version(param.__version__)  # noqa
@@ -22,13 +23,7 @@
 
 html_favicon = "_static/favicon.ico"
 
-html_css_files = [
-    'nbsite.css',
-    'scroller.css',
-    'notebook.css',
-]
-
-exclude_patterns += ['historical_release_notes.rst']  # noqa
+exclude_patterns = ['governance/**/*.*', 'Promo.ipynb']
 
 html_theme_options = {
     "github_url": "https://github.com/holoviz/param",
@@ -49,14 +44,26 @@
             "icon": "fa-brands fa-discord",
         },
     ],
-    "footer_items": [
+    "footer_start": [
         "copyright",
         "last-updated",
     ],
     "analytics": {"google_analytics_id": 'G-KD5GGLCB54'}
 }
 
+extensions += [  # noqa
+    'sphinx_copybutton',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary',
+    'sphinx_remove_toctrees'
+]
+remove_from_toctrees = ["reference/param/generated/*"]
+
 # Override the Sphinx default title that appends `documentation`
 html_title = f'{project} v{version}'
 # Format of the last updated section in the footer
 html_last_updated_fmt = '%Y-%m-%d'
+
+myst_heading_anchors = 3
+
+napoleon_numpy_docstring = True

doc/getting_started.md

@@ -4,16 +4,10 @@
 
 Param has no required dependencies outside of Python's standard library, and so it is very easy to install.
 
-Official releases of Param are available from [conda](https://anaconda.org/ioam/param) and [PyPI](http://pypi.python.org/pypi/param), and can be installed via:
+Official releases of Param are available from conda ([![defaults version](https://img.shields.io/conda/v/anaconda/param.svg?label=defaults&style=flat&colorB=4488ff)](https://anaconda.org/main/param) [![conda-forge version](https://img.shields.io/conda/v/conda-forge/param.svg?label=conda-forge&colorB=4488ff)](https://anaconda.org/conda-forge/param)) and PyPI ([![PyPI version](https://img.shields.io/pypi/v/param.svg?colorB=cc77dd)](https://pypi.org/project/param/)), and can be installed via:
 
 ```
-conda install -c pyviz param
-```
-
-or
-
-```
-pip install --user param
+conda install param
 ```
 
 or
@@ -35,8 +29,8 @@ class A(param.Parameterized):
     title = param.String(default="sum", doc="Title for the result")
 
 class B(A):
-    a = param.Integer(2, bounds=(0,10), doc="First addend")
-    b = param.Integer(3, bounds=(0,10), doc="Second addend")
+    a = param.Integer(2, bounds=(0, 10), doc="First addend")
+    b = param.Integer(3, bounds=(0, 10), doc="Second addend")
 
     def __call__(self):
         return self.title + ": " + str(self.a + self.b)
@@ -94,7 +88,7 @@ Param is valuable for _any_ Python codebase, but it offers features that are par
 
 ```{code-block} python
 >>> import random
->>> o2 = B(a = lambda: random.randint(0,5))
+>>> o2 = B(a=lambda: random.randint(0,5))
 
 >>> o2(), o2(), o2(), o2()
 ('The sum is: 6', 'The sum is: 7', 'The sum is: 3', 'The sum is: 3')
@@ -114,8 +108,8 @@ Param includes a separate and optional module `numbergen` that makes it simple t
 ```{code-block} python
 >>> import numbergen as ng
 
->>> o3 = B(a = ng.Choice(choices=[2,4,6]),
->>>       b = 1+2*ng.UniformRandomInt(ubound=3))
+>>> o3 = B(a=ng.Choice(choices= [2, 4, 6]),
+>>>       b = 1 + 2 * ng.UniformRandomInt(ubound=3))
 
 >>> o3(), o3(), o3(), o3()
 ('The sum is: 11', 'The sum is: 3', 'The sum is: 13', 'The sum is: 7')

doc/index.md

@@ -23,13 +23,12 @@ To quickly see how Param works and can be used, jump straight into the [Getting
 ---
 hidden: true
 ---
-Introduction <self>
 Getting Started <getting_started>
 User Guide <user_guide/index>
 Comparisons <comparisons>
-Roadmap <roadmap>
+API <reference/index>
 Releases <releases>
-API <reference>
+Roadmap <roadmap>
 Developer Guide <developer_guide>
 About <about>
 ```

doc/reference/index.md

@@ -0,0 +1,13 @@
+# API reference
+
+Param effectively installs two packages `param` and `numbergen` importable
+under the same names. This section documents their public API.
+
+
+```{toctree}
+---
+maxdepth: 2
+---
+Param <param/index>
+Numbergen <numbergen>
+```

doc/reference/numbergen.md

@@ -0,0 +1,8 @@
+# Numbergen API reference
+
+```{eval-rst}
+.. automodule:: numbergen
+  :members:
+  :inherited-members:
+  :show-inheritance:
+```

doc/reference/param/index.md

@@ -0,0 +1,57 @@
+# Param API reference
+
+## Parameterized objects
+
+```{include} parameterized_objects.md
+:start-line: 2
+```
+
+## Parameterized helpers
+
+```{include} parameterized_helpers.md
+:start-line: 2
+```
+
+## Parameters
+
+```{include} parameters.md
+:start-line: 2
+```
+
+## Parameter helpers
+
+```{include} parameter_helpers.md
+:start-line: 2
+```
+
+## `.param` namespace
+
+```{include} param_namespace.md
+:start-line: 2
+```
+
+## Logging
+
+```{include} logging.md
+:start-line: 2
+```
+
+## Serialization
+
+```{include} serialization.md
+:start-line: 2
+```
+
+```{toctree}
+---
+maxdepth: 2
+hidden: true
+---
+Parameterized objects <parameterized_objects>
+Parameterized helpers <parameterized_helpers>
+Parameters <parameters>
+Parameter helpers <parameter_helpers>
+Param namespace <param_namespace>
+Logging <logging>
+Serialization <serialization>
+```

doc/reference/param/logging.md

@@ -0,0 +1,9 @@
+# Logging
+
+```{eval-rst}
+.. autosummary::
+  :toctree: generated/
+
+  param.parameterized.get_logger
+  param.parameterized.logging_level
+```