Add how-to for copying objects (#854)

Add a how-to guide which explains how to use the recursive_copy
function. The guide builds up understanding of the function
parameters by showing examples of their use.

Add a parameter ``label_by_id`` to the model printer, since it
is more convenient to know the ID rather than the name when
trying to access objects in the model. Additionally, it allows
distinguishing between the original object and its copy.

Modify the doctest flags to normalize whitespace. Without this,
the tree print output failed to match.

Closes #830.

Author: greschd

doc/source/conf.py

@@ -1,6 +1,7 @@
 """Sphinx documentation configuration file."""
 
 from datetime import datetime
+import doctest
 import inspect
 import os
 import pathlib
@@ -191,6 +192,13 @@ def _signature(
     "pyvista.ext.viewer_directive",
 ]
 
+doctest_default_flags = (
+    doctest.NORMALIZE_WHITESPACE
+    | doctest.ELLIPSIS
+    | doctest.IGNORE_EXCEPTION_DETAIL
+    | doctest.DONT_ACCEPT_TRUE_FOR_1
+)
+
 # Intersphinx mapping
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),