From ff4bbe4bd4e32c3458114aa5a6326b5c164b38ef Mon Sep 17 00:00:00 2001 From: maximlt Date: Tue, 1 Aug 2023 21:50:51 +0200 Subject: [PATCH 01/15] docs refactoring --- .gitignore | 5 +- README.md | 2 +- {examples => doc}/Promo.ipynb | 12 +- doc/about.md | 2 +- {examples => doc}/assets/logo_stacked.png | Bin .../assets/param-is-powerful.png | Bin {examples => doc}/assets/param_help.png | Bin doc/comparisons.md | 4 +- doc/conf.py | 27 +-- doc/getting_started.md | 20 +-- doc/index.md | 5 +- doc/reference.rst | 91 ---------- doc/reference/index.md | 13 ++ doc/reference/numbergen.md | 8 + doc/reference/param.md | 160 ++++++++++++++++++ doc/releases.md | 2 +- .../Dependencies_and_Watchers.ipynb | 20 +-- .../user_guide/Dynamic_Parameters.ipynb | 4 +- .../user_guide/How_Param_Works.ipynb | 0 .../user_guide/Logging_and_Warnings.ipynb | 0 {examples => doc}/user_guide/Outputs.ipynb | 2 +- .../user_guide/Parameter_Types.ipynb | 12 +- .../user_guide/ParameterizedFunctions.ipynb | 0 {examples => doc}/user_guide/Parameters.ipynb | 0 .../Serialization_and_Persistence.ipynb | 0 .../user_guide/Simplifying_Codebases.ipynb | 0 doc/user_guide/index.md | 2 +- param/__init__.py | 12 +- param/parameterized.py | 28 +-- pyproject.toml | 9 +- 30 files changed, 264 insertions(+), 176 deletions(-) rename {examples => doc}/Promo.ipynb (91%) rename {examples => doc}/assets/logo_stacked.png (100%) rename {examples => doc}/assets/param-is-powerful.png (100%) rename {examples => doc}/assets/param_help.png (100%) delete mode 100644 doc/reference.rst create mode 100644 doc/reference/index.md create mode 100644 doc/reference/numbergen.md create mode 100644 doc/reference/param.md rename {examples => doc}/user_guide/Dependencies_and_Watchers.ipynb (96%) rename {examples => doc}/user_guide/Dynamic_Parameters.ipynb (99%) rename {examples => doc}/user_guide/How_Param_Works.ipynb (100%) rename {examples => doc}/user_guide/Logging_and_Warnings.ipynb (100%) rename {examples => doc}/user_guide/Outputs.ipynb (98%) rename {examples => doc}/user_guide/Parameter_Types.ipynb (99%) rename {examples => doc}/user_guide/ParameterizedFunctions.ipynb (100%) rename {examples => doc}/user_guide/Parameters.ipynb (100%) rename {examples => doc}/user_guide/Serialization_and_Persistence.ipynb (100%) rename {examples => doc}/user_guide/Simplifying_Codebases.ipynb (100%) diff --git a/.gitignore b/.gitignore index dbfa61e24..ce9852243 100644 --- a/.gitignore +++ b/.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 diff --git a/README.md b/README.md index c731be395..dedd142c4 100644 --- a/README.md +++ b/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. diff --git a/examples/Promo.ipynb b/doc/Promo.ipynb similarity index 91% rename from examples/Promo.ipynb rename to doc/Promo.ipynb index 8741f6cf6..d17e1742a 100644 --- a/examples/Promo.ipynb +++ b/doc/Promo.ipynb @@ -361,13 +361,13 @@ "\n", "\n", "\n", - " \n", - " \n", + " \n", + " \n", " \n", - " \n", - " \n", - " \n", - " \n", + " \n", + " \n", + " \n", + " \n", "\n", "
" ] diff --git a/doc/about.md b/doc/about.md index 509861bd9..e7f112227 100644 --- a/doc/about.md +++ b/doc/about.md @@ -2,7 +2,7 @@ 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. diff --git a/examples/assets/logo_stacked.png b/doc/assets/logo_stacked.png similarity index 100% rename from examples/assets/logo_stacked.png rename to doc/assets/logo_stacked.png diff --git a/examples/assets/param-is-powerful.png b/doc/assets/param-is-powerful.png similarity index 100% rename from examples/assets/param-is-powerful.png rename to doc/assets/param-is-powerful.png diff --git a/examples/assets/param_help.png b/doc/assets/param_help.png similarity index 100% rename from examples/assets/param_help.png rename to doc/assets/param_help.png diff --git a/doc/comparisons.md b/doc/comparisons.md index 5f1bd9d9f..a5510ba74 100644 --- a/doc/comparisons.md +++ b/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) diff --git a/doc/conf.py b/doc/conf.py index d00961047..d909a147f 100644 --- a/doc/conf.py +++ b/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,24 @@ "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', +] + # 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 diff --git a/doc/getting_started.md b/doc/getting_started.md index 853b40259..d741d24ae 100644 --- a/doc/getting_started.md +++ b/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) [![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)), 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') diff --git a/doc/index.md b/doc/index.md index fb2e0be06..54b99e5e7 100644 --- a/doc/index.md +++ b/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 Getting Started User Guide Comparisons -Roadmap +API Releases -API +Roadmap Developer Guide About ``` diff --git a/doc/reference.rst b/doc/reference.rst deleted file mode 100644 index 9ce8b8a06..000000000 --- a/doc/reference.rst +++ /dev/null @@ -1,91 +0,0 @@ -******************** -API Reference Manual -******************** - -The Param API Reference Manual provides a comprehensive reference for -all modules, functions, classes, and methods provided by Param. See the -`User Guide <../user_guide>`_ for a more readable overview and explanations; -this material duplicates what is available from `help(obj)` for each object. - -`parameterized`_ - Parameter, Parameterized, and other core classes and methods -`param`_ - Optional predefined parameter types like Number, Selector, etc. -`ipython`_ - Optional help functions tailored for Jupyter and IPython -`serializer`_ - Optional JSON serialization -`version`_ - Automatic generation of version strings using version control - - -parameterized Module -==================== - -.. inheritance-diagram:: param.parameterized - ---------------------------- - -.. automodule:: param.parameterized - :members: - :inherited-members: - :show-inheritance: - - -param Module -=============== - -.. inheritance-diagram:: param.__init__ - ----------------------- - -.. automodule:: param.__init__ - :members: - :inherited-members: - :show-inheritance: - - -ipython Module -============== - -.. inheritance-diagram:: param.ipython - ---------------------- - -.. automodule:: param.ipython - :members: - :inherited-members: - :show-inheritance: - - -serializer Module -================= - -.. inheritance-diagram:: param.serializer - ------------------------- - -.. automodule:: param.serializer - :members: - :inherited-members: - :show-inheritance: - - -version Module -============== - -.. inheritance-diagram:: param.version - ---------------------- - -.. automodule:: param.version - :members: - :inherited-members: - :show-inheritance: - - -.. _parameterized: #parameterized-module -.. _param: #param-module -.. _ipython: #ipython-module -.. _serializer: #serializer-module -.. _version: #version-module diff --git a/doc/reference/index.md b/doc/reference/index.md new file mode 100644 index 000000000..1c24312d1 --- /dev/null +++ b/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 +--- +Overview +param +numbergen +``` diff --git a/doc/reference/numbergen.md b/doc/reference/numbergen.md new file mode 100644 index 000000000..7083cc45b --- /dev/null +++ b/doc/reference/numbergen.md @@ -0,0 +1,8 @@ +# Numbergen API reference + +```{eval-rst} +.. automodule:: numbergen + :members: + :inherited-members: + :show-inheritance: +``` diff --git a/doc/reference/param.md b/doc/reference/param.md new file mode 100644 index 000000000..9cccfed31 --- /dev/null +++ b/doc/reference/param.md @@ -0,0 +1,160 @@ +# Param API reference + +## Main objects + +```{eval-rst} +.. currentmodule:: param +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + :nosignatures: + + Parameterized + ParameterizedFunction + ParamOverrides +``` + +## `.param` namespace + +```{eval-rst} +.. currentmodule:: param.parameterized +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + ~Parameters.add_parameter + ~Parameters.debug + ~Parameters.defaults + ~Parameters.deserialize_parameters + ~Parameters.deserialize_value + ~Parameters.force_new_dynamic_value + ~Parameters.get_param_values + ~Parameters.get_value_generator + ~Parameters.inspect_value + ~Parameters.log + ~Parameters.message + ~Parameters.method_dependencies + ~Parameters.objects + ~Parameters.outputs + ~Parameters.params + ~Parameters.params_depended_on + ~Parameters.pprint + ~Parameters.print_param_defaults + ~Parameters.print_param_values + ~Parameters.schema + ~Parameters.set_default + ~Parameters.set_dynamic_time_fn + ~Parameters.set_param + ~Parameters.serialize_parameters + ~Parameters.serialize_value + ~Parameters.trigger + ~Parameters.unwatch + ~Parameters.update + ~Parameters.values + ~Parameters.verbose + ~Parameters.warning + ~Parameters.watch + ~Parameters.watch_values + ~Parameters.watchers +``` + +## Parameterized helpers + +```{eval-rst} +.. currentmodule:: param +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + param.parameterized.Event + param.parameterized.Watcher + batch_watch + param.parameterized.batch_call_watchers + concrete_descendents + depends + discard_events + edit_constant + output + script_repr +``` + +## Logging + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + param.parameterized.get_logger + param.parameterized.logging_level +``` + +## Parameters + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + :nosignatures: + + Parameter + String + Bytes + Color + Boolean + Event + Dynamic + Number + Integer + Magnitude + Tuple + NumericTuple + XYCoordinates + Range + DateRange + CalendarDateRange + List + HookList + Path + Filename + Foldername + CalendarDateRange + Selector + FileSelector + ListSelector + MultiFileSelector + ClassSelector + Dict + Array + Series + DataFrame + Callable + Action + Composite +``` + +## Parameter helpers + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + get_soft_bounds + guess_bounds + guess_param_types + param_union +``` + +## Serialization + + + +```{eval-rst} +.. automodule :: param.serializer + :members: + :undoc-members: +``` diff --git a/doc/releases.md b/doc/releases.md index 499a9a056..20a6d5888 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -304,7 +304,7 @@ Notable changes, fixes, and additions since the previous release (1.5.1) are lis Changes: * `param.__version__` is now a string -* `param.version.Version` now supports a tag-based versioning workflow; if using the `Version` class, you will need to update your workflow (see [autover](https://github.com/holoviz/autover) for more details). +* `param.version.Version` now supports a tag-based versioning workflow; if using the `Version` class, you will need to update your workflow (see [autover](https://github.com/holoviz-dev/autover) for more details). * Dropped support for python 2.6 ([#175](https://github.com/holoviz/param/pull/175)). * No longer attempt to cythonize param during installation via pip ([#166](https://github.com/holoviz/param/pull/166), [#194](https://github.com/holoviz/param/pull/194)). diff --git a/examples/user_guide/Dependencies_and_Watchers.ipynb b/doc/user_guide/Dependencies_and_Watchers.ipynb similarity index 96% rename from examples/user_guide/Dependencies_and_Watchers.ipynb rename to doc/user_guide/Dependencies_and_Watchers.ipynb index 1fe74243f..8b5be3d55 100644 --- a/examples/user_guide/Dependencies_and_Watchers.ipynb +++ b/doc/user_guide/Dependencies_and_Watchers.ipynb @@ -14,9 +14,9 @@ "\n", "This user guide is structured as three main sections:\n", "\n", - "- [Dependencies](#Dependencies): High-level dependency declaration via the `@param.depends()` decorator\n", - "- [Watchers](#Watchers): Low-level watching mechanism via `.param.watch()`.\n", - "- [Using dependencies and watchers](#Using-dependencies-and-watchers): Utilities and tools for working with events created using either dependencies or watchers." + "- [Dependencies](#dependencies): High-level dependency declaration via the `@param.depends()` decorator\n", + "- [Watchers](#watchers): Low-level watching mechanism via `.param.watch()`.\n", + "- [Using dependencies and watchers](#using-dependencies-and-watchers): Utilities and tools for working with events created using either dependencies or watchers." ] }, { @@ -87,7 +87,7 @@ "\n", "1. First, we set up the default continent but do not declare the `objects` and `default` for the `country` parameter. This is because this parameter is dependent on the `continent` and therefore it is easy to set up values that are inconsistent and makes it difficult to override the default continent since changes to both parameters need to be coordinated. \n", "2. Next, if someone chooses a different continent, the list of countries allowed needs to be updated, so the method `_update_countries()` that (a) looks up the countries allowed for the current continent, (b) sets that list as the allowed objects for the `country` parameter, and (c) selects the first such country as the default country.\n", - "3. Finally, we expressed that the `_update_countries()` method depends on the `continent` parameter. We specified `watch=True`) to direct Param to invoke this method immediately, whenever the value of `continent` changes. We'll see [examples of watch=False](#watch=False-dependencies) later. Importantly we also set `on_init=True`, which means that when instance is created the `self._update_countries()` method is automatically called setting up the `country` parameter appropriately. This avoids having to declare a `__init__` method to manually call the method ourselves and the potentially brittle process of setting up consistent defaults." + "3. Finally, we expressed that the `_update_countries()` method depends on the `continent` parameter. We specified `watch=True` to direct Param to invoke this method immediately, whenever the value of `continent` changes. We'll see [examples of watch=False](#watch-false-dependencies) later. Importantly we also set `on_init=True`, which means that when instance is created the `self._update_countries()` method is automatically called setting up the `country` parameter appropriately. This avoids having to declare a `__init__` method to manually call the method ourselves and the potentially brittle process of setting up consistent defaults." ] }, { @@ -553,12 +553,12 @@ "\n", "Whether you use the `watch` or the `depends` approach, Param will store a set of `Watcher` objects on each `Parameterized` object that let it manage and process `Event`s. Param provides various context managers, methods, and Parameters that help you work with Watchers and Events:\n", "\n", - "- [`batch_call_watchers`](#batch_call_watchers): context manager accumulating and eliding multiple Events to be applied on exit from the context \n", - "- [`discard_events`](#discard_events): context manager silently discarding events generated while in the context\n", - "- [`.param.trigger`](#.param.trigger): method to force creation of an Event for this Parameter's Watchers without a corresponding change to the Parameter\n", - "- [`.param.watchers`](#.param.watchers): writable property to access the instance watchers\n", - "- [Event Parameter](#Event-Parameter): Special Parameter type providing triggerable transient Events (like a momentary push button)\n", - "- [Async executor](#Async-executor): Support for asynchronous processing of Events, e.g. for interfacing to external servers\n", + "- [`batch_call_watchers`](#batch-call-watchers): context manager accumulating and eliding multiple Events to be applied on exit from the context \n", + "- [`discard_events`](#discard-events): context manager silently discarding events generated while in the context\n", + "- [`.param.trigger`](#param-trigger): method to force creation of an Event for this Parameter's Watchers without a corresponding change to the Parameter\n", + "- [`.param.watchers`](#param-watchers): writable property to access the instance watchers\n", + "- [Event Parameter](#event-parameter): Special Parameter type providing triggerable transient Events (like a momentary push button)\n", + "- [Async executor](#async-executor): Support for asynchronous processing of Events, e.g. for interfacing to external servers\n", "\n", "Each of these will be described in the following sections." ] diff --git a/examples/user_guide/Dynamic_Parameters.ipynb b/doc/user_guide/Dynamic_Parameters.ipynb similarity index 99% rename from examples/user_guide/Dynamic_Parameters.ipynb rename to doc/user_guide/Dynamic_Parameters.ipynb index de01e3fee..72437d8ca 100644 --- a/examples/user_guide/Dynamic_Parameters.ipynb +++ b/doc/user_guide/Dynamic_Parameters.ipynb @@ -305,7 +305,7 @@ "\n", "Numbergen objects are designed to work seamlessly as Dynamic parameter values, providing easy access to various temporal distributions, along with tools for combining and configuring number generators without having to write custom functions or classes. Moreover, because all of these objects are Parameterized objects sharing the same usage interface (each provides a numeric value when called, regardless of how many or which parameters are required to configure that distribution), using them together with Param's Dynamic support provides a huge amount of power over the values parameters take over time, without requiring any extra complexity in your program. Without Dynamic support and numbergen, your Parameterized classes could of course provide their own support for e.g. a normal random distribution by accepting a mean and variance, but it would then be limited to that specific random distribution, whereas Dynamic parameters can accept _any_ current or future number generator object as configured by a user for their own purposes, neatly separating your Parameterized's requirements (\"a positive integer value\") from the user's requirements (\"let's see what happens when the value starts at 1 and doubles every iteration\").\n", "\n", - "Numbergen objects all inherit from `ng.NumberGenerator`, which defines the callable interface and adds [operator support](#Operations-on-number-generators) as described below. Each type of object then further inherits from either TimeAware (having basic time support) or TimeDependent (TimeAware objects having values that are a strict function of time)." + "Numbergen objects all inherit from `ng.NumberGenerator`, which defines the callable interface and adds [operator support](#operations-on-number-generators) as described below. Each type of object then further inherits from either TimeAware (having basic time support) or TimeDependent (TimeAware objects having values that are a strict function of time)." ] }, { @@ -405,7 +405,7 @@ "\n", "A TimeAware object also has access to a `time_fn` and has a `time_dependent` parameter, but either sets `time_dependent=False` (indicating that values are never a strict function of time) or allows either True or False (switching into and out of a time dependent mode). All current `TimeAware` NumberGenerator objects are random number generators that support both possible values of `time_dependent`. For `time_dependent=False` (the default), they return a new value on each call, while for `time_dependent=True`, they return pseudorandom values that follow the indicated distribution but are also a strict function of the time, in that the same number will be returned for a given time value even if time skips ahead or backwards. \n", "\n", - "These random values are thus very tightly controlled to allow reproducible, repeatable results, with values determined by both a seed value (to choose the overall set of random values) and by the current time. Effectively, when `time_dependent=True`, these numbers provide a random value seeded by the generator's `name` parameter, the global `param.random_seed`, the `seed` parameter of the NumberGenerator, _and_ the NumberGenerator's current `time_fn()` value. The resulting generated values should be the same for a given object and a given `time_fn` value, even across platforms and machine-word sizes (see the [Hash](https://github.com/holoviz/param/blob/main/numbergen/__init__.py#L176), TimeAwareRandomState, and RandomDistribution classes for more details). \n", + "These random values are thus very tightly controlled to allow reproducible, repeatable results, with values determined by both a seed value (to choose the overall set of random values) and by the current time. Effectively, when `time_dependent=True`, these numbers provide a random value seeded by the generator's `name` parameter, the global `param.random_seed`, the `seed` parameter of the NumberGenerator, _and_ the NumberGenerator's current `time_fn()` value. The resulting generated values should be the same for a given object and a given `time_fn` value, even across platforms and machine-word sizes (see the [Hash](https://github.com/holoviz/param/blob/f5208aaac55cf7717e507988e0e733cf2a46e981/numbergen/__init__.py#L201), TimeAwareRandomState, and RandomDistribution classes for more details). \n", "\n", "For best results, you should provide an explicit unique name to any such generator and preserve that name over time, so that results will be reproducible across program runs. By default, the underlying random numbers are generated using Python's [random](https://docs.python.org/3/library/random.html) module (which see for details of the number generation), but you can substitute an instance of `numpy.random.RandomState` or similar compatible object for `self.random_generator` for higher performance or to generate time-dependent array values.\n", "\n", diff --git a/examples/user_guide/How_Param_Works.ipynb b/doc/user_guide/How_Param_Works.ipynb similarity index 100% rename from examples/user_guide/How_Param_Works.ipynb rename to doc/user_guide/How_Param_Works.ipynb diff --git a/examples/user_guide/Logging_and_Warnings.ipynb b/doc/user_guide/Logging_and_Warnings.ipynb similarity index 100% rename from examples/user_guide/Logging_and_Warnings.ipynb rename to doc/user_guide/Logging_and_Warnings.ipynb diff --git a/examples/user_guide/Outputs.ipynb b/doc/user_guide/Outputs.ipynb similarity index 98% rename from examples/user_guide/Outputs.ipynb rename to doc/user_guide/Outputs.ipynb index 0d1fc36e2..801c64798 100644 --- a/examples/user_guide/Outputs.ipynb +++ b/doc/user_guide/Outputs.ipynb @@ -7,7 +7,7 @@ "source": [ "# Outputs\n", "\n", - "Parameters are typically used for the _inputs_ to a Parameterized objects, declaring as precisely as possible which inputs are allowed. You can also declare what _outputs_ are generated by a Parameterized, using `@param.output`. At present, Param itself does not use output declarations internally, but they can be queried by Param-based programs to allow safe chaining of Parameterized objects into pipelines, such as for the [boxflow](https://github.com/ioam/boxflow) dataflow programming system or the multi-page pipelines in [Panel](https://panel.holoviz.org/user_guide/Pipelines.html). \n", + "Parameters are typically used for the _inputs_ to a Parameterized objects, declaring as precisely as possible which inputs are allowed. You can also declare what _outputs_ are generated by a Parameterized, using `@param.output`. At present, Param itself does not use output declarations internally, but they can be queried by Param-based programs to allow safe chaining of Parameterized objects into pipelines, such as for the [boxflow](https://github.com/ioam/boxflow) dataflow programming system or the multi-page pipelines in [Panel](https://panel.holoviz.org/how_to/pipeline/index.html). \n", "\n", "`@param.output` annotates a method on a Parameterized class to declare that it returns one or more outputs of a specified type. As a simple example, this declaration indicates that the given function returns a number:" ] diff --git a/examples/user_guide/Parameter_Types.ipynb b/doc/user_guide/Parameter_Types.ipynb similarity index 99% rename from examples/user_guide/Parameter_Types.ipynb rename to doc/user_guide/Parameter_Types.ipynb index 9671648cc..3c758bf64 100644 --- a/examples/user_guide/Parameter_Types.ipynb +++ b/doc/user_guide/Parameter_Types.ipynb @@ -37,11 +37,11 @@ " - [FileSelector](#selectors): One filename selected out of those matching a provided glob\n", " - [ListSelector](#selectors): Multiple objects selected out of a provided list of objects\n", " - [MultiFileSelector](#selectors): Multiple filenames selected out of those matching a provided glob\n", - " * [ClassSelector](#classSelectors): An instance or class of a specified Python class or superclass\n", - " - [Dict](#classSelectors): A Python dictionary\n", - " - [Array](#classSelectors): NumPy array\n", - " - [Series](#classSelectors): A Pandas Series\n", - " - [DataFrame](#classSelectors): A Pandas DataFrame\n", + " * [ClassSelector](#classselectors): An instance or class of a specified Python class or superclass\n", + " - [Dict](#classselectors): A Python dictionary\n", + " - [Array](#classselectors): NumPy array\n", + " - [Series](#classselectors): A Pandas Series\n", + " - [DataFrame](#classselectors): A Pandas DataFrame\n", "- [Callable](#invocations): A callable object, such as a function.\n", " * [Action](#invocations): A callable with no arguments, ready to invoke\n", "- [Composite](#invocations): A list of other attributes or parameters of this class, settable and readable as a group" @@ -474,7 +474,7 @@ "\n", "A tuple Parameter accepts a Python tuple for the value. Tuple parameters have a fixed length, typically set by the default value of the parameter but settable as the `length` if the default value is None. Only a tuple of the specified length will be accepted when a value is set.\n", "\n", - "There are many tuple types as listed above, accepting either any type, numeric types, datetimes, dates, etc. `Range` types support `bounds`, `softbounds`, `inclusive_bounds`, and `step` on the numeric values in the tuple, similar to [Number](#Numbers) types." + "There are many tuple types as listed above, accepting either any type, numeric types, datetimes, dates, etc. `Range` types support `bounds`, `softbounds`, `inclusive_bounds`, and `step` on the numeric values in the tuple, similar to [Number](#numbers) types." ] }, { diff --git a/examples/user_guide/ParameterizedFunctions.ipynb b/doc/user_guide/ParameterizedFunctions.ipynb similarity index 100% rename from examples/user_guide/ParameterizedFunctions.ipynb rename to doc/user_guide/ParameterizedFunctions.ipynb diff --git a/examples/user_guide/Parameters.ipynb b/doc/user_guide/Parameters.ipynb similarity index 100% rename from examples/user_guide/Parameters.ipynb rename to doc/user_guide/Parameters.ipynb diff --git a/examples/user_guide/Serialization_and_Persistence.ipynb b/doc/user_guide/Serialization_and_Persistence.ipynb similarity index 100% rename from examples/user_guide/Serialization_and_Persistence.ipynb rename to doc/user_guide/Serialization_and_Persistence.ipynb diff --git a/examples/user_guide/Simplifying_Codebases.ipynb b/doc/user_guide/Simplifying_Codebases.ipynb similarity index 100% rename from examples/user_guide/Simplifying_Codebases.ipynb rename to doc/user_guide/Simplifying_Codebases.ipynb diff --git a/doc/user_guide/index.md b/doc/user_guide/index.md index 145f249e5..5bca12eaa 100644 --- a/doc/user_guide/index.md +++ b/doc/user_guide/index.md @@ -12,7 +12,7 @@ This user guide provides detailed information about how to use Param, assuming y - [ParameterizedFunctions](./ParameterizedFunctions): Parameterized function objects, for configurable callables - [Dynamic Parameters](./Dynamic_Parameters): Using dynamic parameter values with and without Numbergen - [How Param Works](./How_Param_Works): Internal details, for Param developers and power users -- [Using Param in GUIs](https://panel.holoviz.org/user_guide/Param.html): (external site) Using Param with Panel to make GUIs +- [Using Param in GUIs](https://panel.holoviz.org/how_to/param/index.html): (external site) Using Param with Panel to make GUIs ```{toctree} --- diff --git a/param/__init__.py b/param/__init__.py index ffd95d5b3..01de90795 100644 --- a/param/__init__.py +++ b/param/__init__.py @@ -99,7 +99,7 @@ def produce_value(value_obj): object: if the object is callable, call it, otherwise return the object. - ..deprecated:: 2.0.0 + .. deprecated:: 2.0.0 """ return _produce_value(value_obj) @@ -111,7 +111,7 @@ def as_unicode(obj): Safely casts any object to unicode including regular string (i.e. bytes) types in python 2. - ..deprecated:: 2.0.0 + .. deprecated:: 2.0.0 """ return str(obj) @@ -123,7 +123,7 @@ def is_ordered_dict(d): Predicate checking for ordered dictionaries. OrderedDict is always ordered, and vanilla Python dictionaries are ordered for Python 3.6+ - ..deprecated:: 2.0.0 + .. deprecated:: 2.0.0 """ py3_ordered_dicts = (sys.version_info.major == 3) and (sys.version_info.minor >= 6) vanilla_odicts = (sys.version_info.major > 3) or py3_ordered_dicts @@ -158,7 +158,7 @@ def hashable(x): part of the object has changed. Does not (currently) recursively replace mutable subobjects. - ..deprecated:: 2.0.0 + .. deprecated:: 2.0.0 """ return _hashable(x) @@ -205,7 +205,7 @@ def named_objs(objlist, namesdict=None): an optional name,obj dictionary, which will override any other name if that item is present in the dictionary. - ..deprecated:: 2.0.0 + .. deprecated:: 2.0.0 """ return _named_objs(objlist, namesdict=namesdict) @@ -2536,7 +2536,7 @@ def abbreviate_paths(pathspec,named_paths): Given a dict of (pathname,path) pairs, removes any prefix shared by all pathnames. Helps keep menu items short yet unambiguous. - ..deprecated:: 2.0.0 + .. deprecated:: 2.0.0 """ return _abbreviate_paths(pathspec, named_paths) diff --git a/param/parameterized.py b/param/parameterized.py index e1760fbe7..e97336121 100644 --- a/param/parameterized.py +++ b/param/parameterized.py @@ -429,7 +429,7 @@ def recursive_repr(fillvalue='...'): """ Decorator to make a repr function return fillvalue for a recursive call - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 """ warnings.warn( 'recursive_repr has been deprecated and will be removed in a future version.', @@ -2031,7 +2031,7 @@ def _repr_html_(self_, open=True): def print_param_defaults(self_): """Print the default values of all cls's Parameters. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")` """ cls = self_.cls @@ -2047,7 +2047,7 @@ def set_default(self_,param_name,value): Equivalent to setting param_name on the class. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `p.param.default =` """ cls = self_.cls @@ -2075,7 +2075,7 @@ def add_parameter(self_, param_name, param_obj): def _add_parameter(self_,param_name, param_obj): """Add a new Parameter object into this object's class. - ..deprecated :: 1.12.0 + .. deprecated :: 1.12.0 """ return self_.add_parameter(param_name, param_obj) @@ -2089,7 +2089,7 @@ def params(self_, parameter_name=None): Includes Parameters from this class and its superclasses. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `.param.values()` or `.param['param']` """ pdict = self_.objects(instance='existing') @@ -2170,7 +2170,7 @@ def set_param(self_, *args,**kwargs): positional arguments, but the keyword interface is preferred because it is more compact and can set multiple values. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `.param.update` """ self_or_cls = self_.self_or_cls @@ -2407,7 +2407,7 @@ def get_param_values(self_, onlychanged=False): only return values that are not equal to the default value (onlychanged has no effect when called on a class). - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use `.param.values().items()` instead (or `.param.values()` for the common case of `dict(....param.get_param_values())`) """ @@ -2549,7 +2549,7 @@ def params_depended_on(self_, *args, **kwargs): returned as these are primarily useful for internal use to determine when a sub-object dependency has to be updated. - ..deprecated: 2.0.0 + .. deprecated: 2.0.0 Use instead `.param.method_dependencies` """ return self_.method_dependencies(*args, **kwargs) @@ -2788,7 +2788,7 @@ def defaults(self_): Note that a Parameter for which instantiate==True has its default instantiated. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `{k:v.default for k,v in p.param.objects().items()}` """ self = self_.self @@ -2824,7 +2824,7 @@ def __db_print(self_,level,msg,*args,**kw): def print_param_values(self_): """Print the values of all this object's Parameters. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")` """ self = self_.self @@ -2849,7 +2849,7 @@ def message(self_,msg,*args,**kw): See Python's logging module for details of message formatting. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `.param.log(param.MESSAGE, ...)` """ self_.__db_print(INFO,msg,*args,**kw) @@ -2862,7 +2862,7 @@ def verbose(self_,msg,*args,**kw): See Python's logging module for details of message formatting. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `.param.log(param.VERBOSE, ...)` """ self_.__db_print(VERBOSE,msg,*args,**kw) @@ -2875,7 +2875,7 @@ def debug(self_,msg,*args,**kw): See Python's logging module for details of message formatting. - ..deprecated:: 1.12.0 + .. deprecated:: 1.12.0 Use instead `.param.log(param.DEBUG, ...)` """ self_.__db_print(DEBUG,msg,*args,**kw) @@ -4181,7 +4181,7 @@ class overridable_property: The same as Python's "property" attribute, but allows the accessor methods to be overridden in subclasses. - ..deprecated:: 2.0.0 + .. deprecated:: 2.0.0 """ # Delays looking up the accessors until they're needed, rather # than finding them when the class is first created. diff --git a/pyproject.toml b/pyproject.toml index be7651084..6330cb4ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,7 +40,7 @@ examples = [ ] doc = [ "param[examples]", - "nbsite ==0.8.0", + "nbsite ==0.8.2", ] tests = [ "coverage[toml]", @@ -135,7 +135,7 @@ post-install-commands = [ [tool.hatch.envs.default.scripts] tests = "pytest {args:tests}" -examples = "pytest -n logical --dist loadscope --nbval-lax {args:examples}" +examples = "pytest -n logical --dist loadscope --nbval-lax {args:doc}" [tool.hatch.envs.docs] template = "docs" @@ -144,8 +144,7 @@ python = "3.9" [tool.hatch.envs.docs.scripts] build = [ - "cp examples/user_guide/*.ipynb doc/user_guide/", - "python -m nbsite build --org holoviz --project-name param", + "python -m sphinx-build -b html doc builtdocs", ] [tool.hatch.envs.tests] @@ -210,7 +209,7 @@ python = [ ] [tool.hatch.envs.tests_examples.scripts] -examples = "pytest -v -n logical --dist loadscope --nbval-lax {args:examples}" +examples = "pytest -v -n logical --dist loadscope --nbval-lax {args:doc}" [tool.pytest.ini_options] python_files = "test*.py" From 2dee4b1b89538ee8c46c30eb6e053bbcb80c39c7 Mon Sep 17 00:00:00 2001 From: maximlt Date: Tue, 1 Aug 2023 22:12:42 +0200 Subject: [PATCH 02/15] test linking to the API --- doc/reference/param.md | 3 +++ doc/user_guide/Parameter_Types.ipynb | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/reference/param.md b/doc/reference/param.md index 9cccfed31..fddeb77d0 100644 --- a/doc/reference/param.md +++ b/doc/reference/param.md @@ -18,6 +18,9 @@ ## `.param` namespace +These methods and properties are available under the `.param` namespace +of {py:class}`Parameterized` classes and instances. + ```{eval-rst} .. currentmodule:: param.parameterized ``` diff --git a/doc/user_guide/Parameter_Types.ipynb b/doc/user_guide/Parameter_Types.ipynb index 3c758bf64..d5235fae9 100644 --- a/doc/user_guide/Parameter_Types.ipynb +++ b/doc/user_guide/Parameter_Types.ipynb @@ -62,9 +62,9 @@ "source": [ "## Strings\n", "\n", - "- `param.String`: String value, with optional regular expression (regex) constraints\n", + "- {py:class}`param.String`: String value, with optional regular expression (regex) constraints\n", "\n", - "A `param.String` may be set to any Python string value by default, or it may be constrained to match a provided regular expression `regex`. Like all other Parameters, it can optionally also `allow_None`, which will be true by default if the default value is None." + "A {py:class}`param.String` may be set to any Python string value by default, or it may be constrained to match a provided regular expression `regex`. Like all other Parameters, it can optionally also `allow_None`, which will be true by default if the default value is None." ] }, { From b5d91e535619824d8156b69452c1cd06687cbbf5 Mon Sep 17 00:00:00 2001 From: maximlt Date: Tue, 1 Aug 2023 22:15:27 +0200 Subject: [PATCH 03/15] other format more appropriate for notebooks --- doc/user_guide/Parameter_Types.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/Parameter_Types.ipynb b/doc/user_guide/Parameter_Types.ipynb index d5235fae9..c05704fff 100644 --- a/doc/user_guide/Parameter_Types.ipynb +++ b/doc/user_guide/Parameter_Types.ipynb @@ -62,9 +62,9 @@ "source": [ "## Strings\n", "\n", - "- {py:class}`param.String`: String value, with optional regular expression (regex) constraints\n", + "- [`param.String`](param.String): String value, with optional regular expression (regex) constraints\n", "\n", - "A {py:class}`param.String` may be set to any Python string value by default, or it may be constrained to match a provided regular expression `regex`. Like all other Parameters, it can optionally also `allow_None`, which will be true by default if the default value is None." + "A [`param.String`](param.String) may be set to any Python string value by default, or it may be constrained to match a provided regular expression `regex`. Like all other Parameters, it can optionally also `allow_None`, which will be true by default if the default value is None." ] }, { From 30aa7551b40d8d24bf68b9ed2c5b9fa403715826 Mon Sep 17 00:00:00 2001 From: maximlt Date: Tue, 1 Aug 2023 22:24:41 +0200 Subject: [PATCH 04/15] fix getting started links --- doc/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index d741d24ae..da6b27e1a 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -4,7 +4,7 @@ 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 (![defaults version](https://img.shields.io/conda/v/anaconda/param.svg?label=defaults&style=flat&colorB=4488ff) [![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)), 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/defaults/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 param From 8c9cd288f7b1592fe01fa0242467303cc4f00279 Mon Sep 17 00:00:00 2001 From: maximlt Date: Tue, 1 Aug 2023 22:26:20 +0200 Subject: [PATCH 05/15] mention forum --- doc/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/about.md b/doc/about.md index e7f112227..8158af945 100644 --- a/doc/about.md +++ b/doc/about.md @@ -4,6 +4,6 @@ Param is completely open source, available under a [BSD license](https://github. 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! From 973b5a11b38cedf4179fa238a0d9854e7ff34369 Mon Sep 17 00:00:00 2001 From: maximlt Date: Tue, 1 Aug 2023 22:46:01 +0200 Subject: [PATCH 06/15] fix command --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 6330cb4ac..3f2886897 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -144,7 +144,7 @@ python = "3.9" [tool.hatch.envs.docs.scripts] build = [ - "python -m sphinx-build -b html doc builtdocs", + "sphinx-build -b html doc builtdocs", ] [tool.hatch.envs.tests] From 01ae16980ecd87f35777d6e8140f6e07e65ea7db Mon Sep 17 00:00:00 2001 From: Maxime Liquet <35924738+maximlt@users.noreply.github.com> Date: Wed, 2 Aug 2023 15:42:35 +0200 Subject: [PATCH 07/15] Update doc/getting_started.md Co-authored-by: Demetris Roumis --- doc/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/getting_started.md b/doc/getting_started.md index da6b27e1a..7fa832cc3 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -4,7 +4,7 @@ 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 ([![defaults version](https://img.shields.io/conda/v/anaconda/param.svg?label=defaults&style=flat&colorB=4488ff)](https://anaconda.org/defaults/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: +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 param From b2bb6043a6bf15db1a9afdf8536d107951ddd868 Mon Sep 17 00:00:00 2001 From: Philipp Rudiger Date: Thu, 17 Aug 2023 12:09:15 +0200 Subject: [PATCH 08/15] Apply suggestions from code review --- doc/reference/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/reference/index.md b/doc/reference/index.md index 1c24312d1..0fd8d82b1 100644 --- a/doc/reference/index.md +++ b/doc/reference/index.md @@ -7,7 +7,6 @@ under the same names. This section documents their public API. --- maxdepth: 2 --- -Overview param numbergen ``` From 969a4348e0a14c12ed7156aac66ca23232b6effb Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Fri, 18 Aug 2023 08:30:35 +0200 Subject: [PATCH 09/15] add sphinx_remove_toctrees plugin --- doc/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index d909a147f..7a27b00b2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -55,7 +55,9 @@ '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}' From cb172d72e40c1eb2f59d7d80e0aad7131d673294 Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Fri, 18 Aug 2023 08:36:54 +0200 Subject: [PATCH 10/15] use include directive to agg sep ref section pages --- doc/reference/index.md | 5 +- doc/reference/param.md | 163 ------------------- doc/reference/param/base_objects.md | 15 ++ doc/reference/param/index.md | 56 +++++++ doc/reference/param/logging.md | 9 + doc/reference/param/param_namespace.md | 48 ++++++ doc/reference/param/parameter_helpers.md | 11 ++ doc/reference/param/parameterized_helpers.md | 21 +++ doc/reference/param/parameters.md | 42 +++++ doc/reference/param/serialization.md | 7 + 10 files changed, 212 insertions(+), 165 deletions(-) delete mode 100644 doc/reference/param.md create mode 100644 doc/reference/param/base_objects.md create mode 100644 doc/reference/param/index.md create mode 100644 doc/reference/param/logging.md create mode 100644 doc/reference/param/param_namespace.md create mode 100644 doc/reference/param/parameter_helpers.md create mode 100644 doc/reference/param/parameterized_helpers.md create mode 100644 doc/reference/param/parameters.md create mode 100644 doc/reference/param/serialization.md diff --git a/doc/reference/index.md b/doc/reference/index.md index 0fd8d82b1..3139e18a1 100644 --- a/doc/reference/index.md +++ b/doc/reference/index.md @@ -3,10 +3,11 @@ Param effectively installs two packages `param` and `numbergen` importable under the same names. This section documents their public API. + ```{toctree} --- maxdepth: 2 --- -param -numbergen +Param +Numbergen ``` diff --git a/doc/reference/param.md b/doc/reference/param.md deleted file mode 100644 index fddeb77d0..000000000 --- a/doc/reference/param.md +++ /dev/null @@ -1,163 +0,0 @@ -# Param API reference - -## Main objects - -```{eval-rst} -.. currentmodule:: param -``` - -```{eval-rst} -.. autosummary:: - :toctree: generated/ - :nosignatures: - - Parameterized - ParameterizedFunction - ParamOverrides -``` - -## `.param` namespace - -These methods and properties are available under the `.param` namespace -of {py:class}`Parameterized` classes and instances. - -```{eval-rst} -.. currentmodule:: param.parameterized -``` - -```{eval-rst} -.. autosummary:: - :toctree: generated/ - - ~Parameters.add_parameter - ~Parameters.debug - ~Parameters.defaults - ~Parameters.deserialize_parameters - ~Parameters.deserialize_value - ~Parameters.force_new_dynamic_value - ~Parameters.get_param_values - ~Parameters.get_value_generator - ~Parameters.inspect_value - ~Parameters.log - ~Parameters.message - ~Parameters.method_dependencies - ~Parameters.objects - ~Parameters.outputs - ~Parameters.params - ~Parameters.params_depended_on - ~Parameters.pprint - ~Parameters.print_param_defaults - ~Parameters.print_param_values - ~Parameters.schema - ~Parameters.set_default - ~Parameters.set_dynamic_time_fn - ~Parameters.set_param - ~Parameters.serialize_parameters - ~Parameters.serialize_value - ~Parameters.trigger - ~Parameters.unwatch - ~Parameters.update - ~Parameters.values - ~Parameters.verbose - ~Parameters.warning - ~Parameters.watch - ~Parameters.watch_values - ~Parameters.watchers -``` - -## Parameterized helpers - -```{eval-rst} -.. currentmodule:: param -``` - -```{eval-rst} -.. autosummary:: - :toctree: generated/ - - param.parameterized.Event - param.parameterized.Watcher - batch_watch - param.parameterized.batch_call_watchers - concrete_descendents - depends - discard_events - edit_constant - output - script_repr -``` - -## Logging - -```{eval-rst} -.. autosummary:: - :toctree: generated/ - - param.parameterized.get_logger - param.parameterized.logging_level -``` - -## Parameters - -```{eval-rst} -.. autosummary:: - :toctree: generated/ - :nosignatures: - - Parameter - String - Bytes - Color - Boolean - Event - Dynamic - Number - Integer - Magnitude - Tuple - NumericTuple - XYCoordinates - Range - DateRange - CalendarDateRange - List - HookList - Path - Filename - Foldername - CalendarDateRange - Selector - FileSelector - ListSelector - MultiFileSelector - ClassSelector - Dict - Array - Series - DataFrame - Callable - Action - Composite -``` - -## Parameter helpers - -```{eval-rst} -.. autosummary:: - :toctree: generated/ - - get_soft_bounds - guess_bounds - guess_param_types - param_union -``` - -## Serialization - - - -```{eval-rst} -.. automodule :: param.serializer - :members: - :undoc-members: -``` diff --git a/doc/reference/param/base_objects.md b/doc/reference/param/base_objects.md new file mode 100644 index 000000000..d8818011a --- /dev/null +++ b/doc/reference/param/base_objects.md @@ -0,0 +1,15 @@ +# Base objects + +```{eval-rst} +.. currentmodule:: param +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + :nosignatures: + + Parameterized + ParameterizedFunction + ParamOverrides +``` diff --git a/doc/reference/param/index.md b/doc/reference/param/index.md new file mode 100644 index 000000000..aa6dfedb2 --- /dev/null +++ b/doc/reference/param/index.md @@ -0,0 +1,56 @@ +# Param API reference + +## Base objects + +```{include} base_objects.md +:start-line: 2 +``` + +## `.param` namespace + +```{include} param_namespace.md +:start-line: 2 +``` + +## Parameterized helpers + +```{include} parameterized_helpers.md +:start-line: 2 +``` + +## Logging + +```{include} logging.md +:start-line: 2 +``` + +## Parameters + +```{include} parameters.md +:start-line: 2 +``` + +## Parameter helpers + +```{include} parameter_helpers.md +:start-line: 2 +``` + +## Serialization + +```{include} serialization.md +:start-line: 2 +``` + +```{toctree} +--- +maxdepth: 2 +hidden: true +--- +Base objects +Param Namespace +Logging +Parameters <./parameters> +Parameter Helpers <./parameter_helpers> +Serialization +``` diff --git a/doc/reference/param/logging.md b/doc/reference/param/logging.md new file mode 100644 index 000000000..83947a772 --- /dev/null +++ b/doc/reference/param/logging.md @@ -0,0 +1,9 @@ +# Logging + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + param.parameterized.get_logger + param.parameterized.logging_level +``` diff --git a/doc/reference/param/param_namespace.md b/doc/reference/param/param_namespace.md new file mode 100644 index 000000000..da7f17e7c --- /dev/null +++ b/doc/reference/param/param_namespace.md @@ -0,0 +1,48 @@ +# `.param` namespace + +These methods and properties are available under the `.param` namespace +of {py:class}`Parameterized` classes and instances. + +```{eval-rst} +.. currentmodule:: param.parameterized +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + ~Parameters.add_parameter + ~Parameters.debug + ~Parameters.defaults + ~Parameters.deserialize_parameters + ~Parameters.deserialize_value + ~Parameters.force_new_dynamic_value + ~Parameters.get_param_values + ~Parameters.get_value_generator + ~Parameters.inspect_value + ~Parameters.log + ~Parameters.message + ~Parameters.method_dependencies + ~Parameters.objects + ~Parameters.outputs + ~Parameters.params + ~Parameters.params_depended_on + ~Parameters.pprint + ~Parameters.print_param_defaults + ~Parameters.print_param_values + ~Parameters.schema + ~Parameters.set_default + ~Parameters.set_dynamic_time_fn + ~Parameters.set_param + ~Parameters.serialize_parameters + ~Parameters.serialize_value + ~Parameters.trigger + ~Parameters.unwatch + ~Parameters.update + ~Parameters.values + ~Parameters.verbose + ~Parameters.warning + ~Parameters.watch + ~Parameters.watch_values + ~Parameters.watchers +``` diff --git a/doc/reference/param/parameter_helpers.md b/doc/reference/param/parameter_helpers.md new file mode 100644 index 000000000..a6c1d82ed --- /dev/null +++ b/doc/reference/param/parameter_helpers.md @@ -0,0 +1,11 @@ +# Parameter helpers + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + get_soft_bounds + guess_bounds + guess_param_types + param_union +``` diff --git a/doc/reference/param/parameterized_helpers.md b/doc/reference/param/parameterized_helpers.md new file mode 100644 index 000000000..6fb6b42aa --- /dev/null +++ b/doc/reference/param/parameterized_helpers.md @@ -0,0 +1,21 @@ +# Parameterized helpers + +```{eval-rst} +.. currentmodule:: param +``` + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + param.parameterized.Event + param.parameterized.Watcher + batch_watch + param.parameterized.batch_call_watchers + concrete_descendents + depends + discard_events + edit_constant + output + script_repr +``` diff --git a/doc/reference/param/parameters.md b/doc/reference/param/parameters.md new file mode 100644 index 000000000..923d4bbbd --- /dev/null +++ b/doc/reference/param/parameters.md @@ -0,0 +1,42 @@ +# Parameters + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + :nosignatures: + + Parameter + String + Bytes + Color + Boolean + Event + Dynamic + Number + Integer + Magnitude + Tuple + NumericTuple + XYCoordinates + Range + DateRange + CalendarDateRange + List + HookList + Path + Filename + Foldername + CalendarDateRange + Selector + FileSelector + ListSelector + MultiFileSelector + ClassSelector + Dict + Array + Series + DataFrame + Callable + Action + Composite +``` diff --git a/doc/reference/param/serialization.md b/doc/reference/param/serialization.md new file mode 100644 index 000000000..1dad4bd57 --- /dev/null +++ b/doc/reference/param/serialization.md @@ -0,0 +1,7 @@ +# Serialization + +```{eval-rst} +.. automodule :: param.serializer + :members: + :undoc-members: +``` From 3c83f26850fe8fc7732423e78dfdd601cfb6187c Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Fri, 18 Aug 2023 09:03:56 +0200 Subject: [PATCH 11/15] rename base to parameterized and reorder --- doc/reference/param/index.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/doc/reference/param/index.md b/doc/reference/param/index.md index aa6dfedb2..a4ec7f59a 100644 --- a/doc/reference/param/index.md +++ b/doc/reference/param/index.md @@ -1,38 +1,38 @@ # Param API reference -## Base objects +## Parameterized objects -```{include} base_objects.md +```{include} parameterized_objects.md :start-line: 2 ``` -## `.param` namespace +## Parameterized helpers -```{include} param_namespace.md +```{include} parameterized_helpers.md :start-line: 2 ``` -## Parameterized helpers +## Parameters -```{include} parameterized_helpers.md +```{include} parameters.md :start-line: 2 ``` -## Logging +## Parameter helpers -```{include} logging.md +```{include} parameter_helpers.md :start-line: 2 ``` -## Parameters +## `.param` namespace -```{include} parameters.md +```{include} param_namespace.md :start-line: 2 ``` -## Parameter helpers +## Logging -```{include} parameter_helpers.md +```{include} logging.md :start-line: 2 ``` @@ -47,10 +47,11 @@ maxdepth: 2 hidden: true --- -Base objects -Param Namespace +Parameterized objects +Parameterized helpers +Parameters +Parameter helpers +Param namespace Logging -Parameters <./parameters> -Parameter Helpers <./parameter_helpers> Serialization ``` From c9bcd429079fb67f5e14f8998a94731ee33f6e0e Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Fri, 18 Aug 2023 09:04:26 +0200 Subject: [PATCH 12/15] move ParamOverrides to Parameter helpers --- doc/reference/param/parameter_helpers.md | 1 + .../param/{base_objects.md => parameterized_objects.md} | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) rename doc/reference/param/{base_objects.md => parameterized_objects.md} (83%) diff --git a/doc/reference/param/parameter_helpers.md b/doc/reference/param/parameter_helpers.md index a6c1d82ed..9bd41be78 100644 --- a/doc/reference/param/parameter_helpers.md +++ b/doc/reference/param/parameter_helpers.md @@ -8,4 +8,5 @@ guess_bounds guess_param_types param_union + ParamOverrides ``` diff --git a/doc/reference/param/base_objects.md b/doc/reference/param/parameterized_objects.md similarity index 83% rename from doc/reference/param/base_objects.md rename to doc/reference/param/parameterized_objects.md index d8818011a..7ff607b9d 100644 --- a/doc/reference/param/base_objects.md +++ b/doc/reference/param/parameterized_objects.md @@ -1,4 +1,4 @@ -# Base objects +# Parameterized objects ```{eval-rst} .. currentmodule:: param @@ -11,5 +11,4 @@ Parameterized ParameterizedFunction - ParamOverrides ``` From bdf492d0ce78fce9e146584dd34441ed2173a94a Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Fri, 18 Aug 2023 09:13:54 +0200 Subject: [PATCH 13/15] add currentmodule param --- doc/reference/param/index.md | 2 +- doc/reference/param/parameter_helpers.md | 4 ++++ doc/reference/param/parameters.md | 4 ++++ 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/reference/param/index.md b/doc/reference/param/index.md index a4ec7f59a..48027db24 100644 --- a/doc/reference/param/index.md +++ b/doc/reference/param/index.md @@ -48,7 +48,7 @@ maxdepth: 2 hidden: true --- Parameterized objects -Parameterized helpers +Parameterized helpers Parameters Parameter helpers Param namespace diff --git a/doc/reference/param/parameter_helpers.md b/doc/reference/param/parameter_helpers.md index 9bd41be78..65e112293 100644 --- a/doc/reference/param/parameter_helpers.md +++ b/doc/reference/param/parameter_helpers.md @@ -1,5 +1,9 @@ # Parameter helpers +```{eval-rst} +.. currentmodule:: param +``` + ```{eval-rst} .. autosummary:: :toctree: generated/ diff --git a/doc/reference/param/parameters.md b/doc/reference/param/parameters.md index 923d4bbbd..ab9f05ed0 100644 --- a/doc/reference/param/parameters.md +++ b/doc/reference/param/parameters.md @@ -1,5 +1,9 @@ # Parameters +```{eval-rst} +.. currentmodule:: param +``` + ```{eval-rst} .. autosummary:: :toctree: generated/ From 7a38a48e785b8d1945164c7d295cf2c627173091 Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Fri, 18 Aug 2023 09:38:07 +0200 Subject: [PATCH 14/15] add sphinx-remove-toctree to pyproject.toml --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 3f2886897..0659c7796 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,6 +41,7 @@ examples = [ doc = [ "param[examples]", "nbsite ==0.8.2", + "sphinx-remove-toctrees", ] tests = [ "coverage[toml]", From 3c3e957048ae2191089b3fa35901ed7f9327e0a8 Mon Sep 17 00:00:00 2001 From: Demetris Roumis Date: Fri, 18 Aug 2023 14:56:11 +0200 Subject: [PATCH 15/15] fix whitespace --- doc/reference/param/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/reference/param/index.md b/doc/reference/param/index.md index 48027db24..c2fd74956 100644 --- a/doc/reference/param/index.md +++ b/doc/reference/param/index.md @@ -40,7 +40,7 @@ ```{include} serialization.md :start-line: 2 -``` +``` ```{toctree} ---