Improve documentation for graph_greedy_color (Qiskit#857)

* Improve documentation for graph_greedy_color

This commit improves the documentation for the graph_greedy_color
function. Previously, the details on the function and the algorithm it
implemented where a bit sparse. This commit expands it by explaining the
source for the algorithm, making it clear it's not always going to
return an optimal solution, and also adding an example.

* Update src/coloring.rs

* Change to use note directive

* Update src/coloring.rs

Co-authored-by: Julien Gacon <[email protected]>

---------

Co-authored-by: Julien Gacon <[email protected]>

src/coloring.rs

@@ -26,13 +26,38 @@ use petgraph::visit::NodeCount;
 
 use rayon::prelude::*;
 
-/// Color a PyGraph using a largest_first strategy greedy graph coloring.
+/// Color a :class:`~.PyGraph` object using a greedy graph coloring algorithm.
+///
+/// This function uses a `largest-first` strategy as described in [1]_ and colors
+/// the nodes with higher degree first.
+///
+/// .. note::
+///
+///     The coloring problem is NP-hard and this is a heuristic algorithm which
+///     may not return an optimal solution.
 ///
 /// :param PyGraph: The input PyGraph object to color
 ///
 /// :returns: A dictionary where keys are node indices and the value is
 ///     the color
 /// :rtype: dict
+///
+/// .. jupyter-execute::
+///
+///     import rustworkx as rx
+///     from rustworkx.visualization import mpl_draw
+///
+///     graph = rx.generators.generalized_petersen_graph(5, 2)
+///     coloring = rx.graph_greedy_color(graph)
+///     colors = [coloring[node] for node in graph.node_indices()]
+///
+///     # Draw colored graph
+///     layout = rx.shell_layout(graph, nlist=[[0, 1, 2, 3, 4],[6, 7, 8, 9, 5]])
+///     mpl_draw(graph, node_color=colors, pos=layout)
+///
+///
+/// .. [1] Adrian Kosowski, and Krzysztof Manuszewski, Classical Coloring of Graphs,
+///     Graph Colorings, 2-19, 2004. ISBN 0-8218-3458-4.
 #[pyfunction]
 #[pyo3(text_signature = "(graph, /)")]
 pub fn graph_greedy_color(py: Python, graph: &graph::PyGraph) -> PyResult<PyObject> {