doc: clean() with examples explaining how to use the arguments

[buhtz]

From the current docu of clean() it is not clear to me how to use the several arguments available in that function.
Examples in the docu would help me a lot.

nh3/src/lib.rs

Lines 8 to 46 in 9d73a46

	/// Sanitize an HTML fragment according to the given options.
	///
	/// :param html: Input HTML fragment
	/// :type html: ``str``
	/// :param tags: Sets the tags that are allowed.
	/// :type tags: ``set[str]``, optional
	/// :param clean_content_tags: Sets the tags whose contents will be completely removed from the output.
	/// :type clean_content_tags: ``set[str]``, optional
	/// :param attributes: Sets the HTML attributes that are allowed on specific tags,
	/// ``*`` key means the attributes are allowed on any tag.
	/// :type attributes: ``dict[str, set[str]]``, optional
	/// :param attribute_filter: Allows rewriting of all attributes using a callback.
	/// The callback takes name of the element, attribute and its value.
	/// Returns ``None`` to remove the attribute, or a value to use.
	/// :type attribute_filter: ``Callable[[str, str, str], str | None]``, optional
	/// :param strip_comments: Configures the handling of HTML comments, defaults to ``True``.
	/// :type strip_comments: ``bool``
	/// :param link_rel: Configures a ``rel`` attribute that will be added on links, defaults to ``noopener noreferrer``.
	/// To turn on rel-insertion, pass a space-separated list.
	/// If ``rel`` is in the generic or tag attributes, this must be set to ``None``. Common ``rel`` values to include:
	///
	/// - ``noopener``: This prevents a particular type of XSS attack, and should usually be turned on for untrusted HTML.
	/// - ``noreferrer``: This prevents the browser from sending the source URL to the website that is linked to.
	/// - ``nofollow``: This prevents search engines from using this link for ranking, which disincentivizes spammers.
	/// :type link_rel: ``str``
	/// :param generic_attribute_prefixes: Sets the prefix of attributes that are allowed on any tag.
	/// :type generic_attribute_prefixes: ``set[str]``, optional
	/// :param tag_attribute_values: Sets the values of HTML attributes that are allowed on specific tags.
	/// The value is structured as a map from tag names to a map from attribute names to a set of attribute values.
	/// If a tag is not itself whitelisted, adding entries to this map will do nothing.
	/// :type tag_attribute_values: ``dict[str, dict[str, set[str]]]``, optional
	/// :param set_tag_attribute_values: Sets the values of HTML attributes that are to be set on specific tags.
	/// The value is structured as a map from tag names to a map from attribute names to an attribute value.
	/// If a tag is not itself whitelisted, adding entries to this map will do nothing.
	/// :type set_tag_attribute_values: ``dict[str, dict[str, str]]``, optional
	/// :param url_schemes: Sets the URL schemes permitted on ``href`` and ``src`` attributes.
	/// :type url_schemes: ``set[str]``, optional
	/// :return: Sanitized HTML fragment
	/// :rtype: ``str``

[messense]

Sorry no example ATM, PR are welcome!

Note that generated api reference is here: https://nh3.readthedocs.io/en/stable/#nh3.clean

[buhtz]

Hello messense,
thank you for the reply.

Sorry no example ATM

No, need to say sorry.

PR are welcome!

I am not able to provide that because I don't understand the arguments in questions.

From maintainer to maintainer: Don't use that phrase. It just drives contributors away because the subtext always is "You lazy user, how dare you to ask for something and not solving it yourself." And it doesn't matter how you (as a sender) mean it. It only counts how the receiver understands it. Please be more kind to your contributors, even those with "stupid" questions, to support FOSS.

Note that generated api reference is here: https://nh3.readthedocs.io/en/stable/#nh3.clean

Thanks for that hint.

[xmo-odoo]

I am not able to provide that because I don't understand the arguments in questions.

FWIW since nh3 is a thin layer over ammonia, ammonia's API docs can generally be used as basis to try and understand the Python side.

Although you need to go through the mapping (in the code), and that assumes it's documented in a way that's understandable on the ammonia side, which is usually the case (as pretty much all methods have examples) but not always (as examples may not show all edge cases).