Merge 9e23577 into e9edfdc

docs/source/index.rst

@@ -40,8 +40,8 @@ Project history
 
 rustworkx was originally called retworkx and was created to be a high
 performance replacement for the Qiskit project's internal usage of the
-`NetworkX <https://networkx.org/>`__ library (which is where the name comes
-from Rust + NetworkX = rustworkx) but it is not a drop-in replacement for
+`NetworkX <https://networkx.org/>`__ library (which is where the name came
+from: Rust + NetworkX = rustworkx) but it is not a drop-in replacement for
 NetworkX (see :ref:`networkx` for more details). However, since it was
 originally created it has grown to be an independent high performance general
 purpose graph library that can be used for any application that needs to
@@ -52,7 +52,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   Overview and Installation <README>
+   Installation and Getting Started <install.rst>
    Rustworkx Tutorials and Guides <tutorial/index>
    Rustworkx API <api>
    Visualization <visualization>

docs/source/install.rst

@@ -0,0 +1,176 @@
+Getting Started
+===============
+
+rustworkx is a general purpose graph library for Python written in Rust to take
+advantage of the performance and safety that Rust provides. It is designed to
+provide a high performance general purpose graph library for any Python
+application.
+
+Installing Rustworkx
+====================
+
+rustworkx is published on pypi so on x86_64, i686, ppc64le, s390x, and aarch64
+Linux systems, x86_64 on Mac OSX, and 32 and 64 bit Windows installing is as
+simple as running::
+
+    pip install rustworkx
+
+This will install a precompiled version of rustworkx into your python
+environment.
+
+.. install-unsupported::
+
+Installing on a platform without precompiled binaries
+-----------------------------------------------------
+
+If there are no precompiled binaries published for your system you'll have to
+build the package from source. However, to be able able to build the package from
+the published source package you need to have Rust >= 1.48.0 installed (and also
+cargo which is normally included with rust) You can use
+`rustup <https://rustup.rs/>`_ (a cross platform installer for rust) to make this
+simpler, or rely on
+`other installation methods <https://forge.rust-lang.org/infra/other-installation-methods.html>`__.
+A source package is also published on PyPI, so you still can run ``pip`` to install
+it. Once you have Rust properly installed, running::
+
+    pip install rustworkx
+
+will build rustworkx for your local system from the source package and install it
+just as it would if there was a prebuilt binary available.
+
+
+.. note::
+
+    To build from source you will need to ensure you have pip >=19.0.0
+    installed, which supports PEP-517, or that you have manually installed
+    setuptools-rust prior to running pip install rustworkx. If you recieve an
+    error about ``setuptools-rust`` not being found you should upgrade pip with
+    ``pip install -U pip`` or manually install ``setuptools-rust`` with:
+    ``pip install setuptools-rust`` and try again.
+
+.. platform-suppport::
+
+Platform Support
+================
+
+Rustworkx strives to support as many platforms as possible, but due to
+limitations in available testing resources and platform availability, not all
+platforms can be supported. Platform support for rustworkx is broken into 4
+tiers with different levels of support for each tier. For platforms outside
+these, rustworkx is probably still installable, but it’s not tested and you will
+need a Rust compiler and have to build retworkx (and likely Numpy too) from
+source.
+
+.. list-table:: Platform Support
+   :header-rows: 1
+
+   * - Operating System
+     - CPU Architecture
+     - Support Tier
+     - Notes 
+   * - Linux
+     - x86_64
+     - :ref:`tier-1`
+     - Distributions compatible with the [manylinux 2010](https://peps.python.org/pep-0571/) packaging specification
+   * - Linux
+     - i686 
+     - :ref:`tier-2` (Python < 3.10), :ref:`tier-3` (Python >= 3.10)
+     - Distributions compatible with the [manylinux 2010](https://peps.python.org/pep-0571/) packaging specification
+   * - Linux
+     - aarch64
+     - :ref:`tier-2`
+     - Distributions compatible with the [manylinux 2014](https://peps.python.org/pep-0599/) packaging specification
+   * - Linux
+     - pp64le
+     - :ref:`tier-3`
+     - Distributions compatible with the [manylinux 2014](https://peps.python.org/pep-0599/) packaging specification
+   * - Linux
+     - s390x
+     - :ref:`tier-3
+     - Distributions compatible with the [manylinux 2014](https://peps.python.org/pep-0599/) packaging specification
+   * - macOS (10.9 or newer)
+     - x86_64
+     - :ref:`tier-1`
+     -
+   * - macOS (10.15 or newer)
+     - arm64
+     - :ref:`tier-4`
+     -
+   * - Windows 64bit
+     - x86_64
+     - :ref:`tier-1`
+     -
+   * - Windows 32bit 
+     - i686 or x86_64
+     - :ref:`tier-2` (Python < 3.10), :ref:`tier-3` (Python >= 3.10)
+     -
+
+.. tier-1::
+
+Tier 1
+------
+
+Tier 1 supported platforms are fully tested upstream as part of the development
+process to ensure any proposed change will function correctly. Pre-compiled
+binaries are built, tested, and published to PyPI as part of the release
+process. These platforms are expected to be installable with just a functioning
+Python environment.
+
+.. tier-2::
+
+Tier 2
+------
+
+Tier 2 platforms are not tested upstream as part of the development process.
+However, pre-compiled binaries are built, tested, and published to PyPI as part
+of the release process and these packages can be expected to be installed with
+just a functioning Python environment.
+
+.. tier-3::
+
+Tier 3
+------
+
+Tier 3 platforms are not tested upstream as part of the development process.
+Pre-compiled binaries are built, tested and published to PyPI as
+part of the release process. However, they may not installable with just a
+functioning Python environment and you may be required to build Numpy from
+source, which requires a C/C++ compiler, as part of the installation process.
+
+.. tier-4::
+
+Tier 4
+------
+
+Tier 4 platforms are not tested upstream as part of the development process.
+Pre-compiled binaries are built and published to PyPI as part of the release
+process, with no testing at all. They may not be installable with just a
+functioning Python environment and may require a C/C++ compiler or additional
+programs to build dependencies from source as part of the installation process.
+Support for these platforms are best effort only.
+
+Using rustworkx
+===============
+
+Once you have rustworkx installed you can use it by importing rustworkx. All the
+functions and graph classes are off the root of the package. For example,
+calculating the shortest path between A and C would be::
+
+    import rustworkx as rx
+    
+    graph = rx.PyGraph()
+    
+    # Each time add node is called, it returns a new node index
+    a = graph.add_node("A")
+    b = graph.add_node("B")
+    c = graph.add_node("C")
+    
+    # add_edges_from takes tuples of node indices and weights,
+    # and returns edge indices
+    graph.add_edges_from([(a, b, 1.5), (a, c, 5.0), (b, c, 2.5)])
+    
+    # Returns the path A -> B -> C
+    rx.dijkstra_shortest_paths(graph, a, c, weight_fn=float)
+
+You can refer to the :ref:`intro-tutorial` for more details on getting started
+with rustworkx.

docs/source/tutorial/introduction.rst

@@ -6,11 +6,37 @@
 Introduction to rustworkx
 #########################
 
+The rustworkx library is a Python library for working with graphs (or networks)
+and graph theory.
+
 This guide serves as an introduction to working with rustworkx. If you're a
 current or past `NetworkX <https:://networkx.org>`__ user who is looking at
 using rustworkx as a replacement for NetworkX, you can also refer to
 :ref:`networkx` for a detailed comparison.
 
+Installing rustworkx
+====================
+
+To install rustworkx you need a Python installation. Rustworkx works in any
+Python environment. If you already have Python, you can install rustworkx with::
+
+    pip install rustworkx
+
+(if you're running on a supported platform, if you're not you will need to
+refer to the :ref:`install-unsupported` on how to build and install)
+
+How to import rustworkx
+=======================
+
+To access rustworkx and its functions import it into your Python code like this:
+
+.. jupyter-execute::
+
+    import rustworkx as rx
+
+We shorten the name to ``rx`` for better readability of code using Rustworkx.
+This is a widely adopted convention that you can follow.
+
 Creating a Graph
 ================
 
@@ -19,7 +45,6 @@ can run the following code:
 
 .. jupyter-execute::
 
-    import rustworkx as rx
     G = rx.PyGraph()
 
 A :class:`~rustworkx.PyGraph` is comprised of nodes (vertices)
@@ -171,8 +196,6 @@ lists of indices for nodes and edges in the graph. For example:
 
 .. jupyter-execute::
 
-    import rustworkx
-
     graph = rustworkx.PyGraph()
     graph.add_nodes_from(list(range(5)))
     graph.add_nodes_from(list(range(2)))
@@ -308,8 +331,6 @@ accessed and modified after creation with the :attr:`~.PyGraph.attrs` attribute.
 This attribute can be any Python object and defaults to being ``None`` if not
 specified at graph object creation time. For example::
 
-    import rustworkx as rx
-
     graph = rx.PyGraph(attrs=dict(day="Friday"))
     graph.attrs['day'] = "Monday"
 
@@ -335,7 +356,6 @@ directed graphs. For example:
 
 .. jupyter-execute::
 
-    import rustworkx as rx
     from rustworkx.visualization import mpl_draw
 
     path_graph = rx.generators.directed_path_graph(5)

rustworkx/__init__.py

@@ -36,9 +36,9 @@ class PyDAG(PyDiGraph):
 
     .. jupyter-execute::
 
-        import rustworkx
+        import rustworkx as rx
 
-        graph = rustworkx.PyDAG()
+        graph = rx.PyDAG()
         graph.add_nodes_from(list(range(5)))
         graph.add_nodes_from(list(range(2)))
         graph.remove_node(2)
@@ -54,9 +54,9 @@ class PyDAG(PyDiGraph):
 
     .. jupyter-execute::
 
-        import rustworkx
+        import rustworkx as rx
 
-        graph = rustworkx.PyDAG()
+        graph = rx.PyDAG()
         data_payload = "An arbitrary Python object"
         node_index = graph.add_node(data_payload)
         print("Node Index: %s" % node_index)
@@ -67,9 +67,9 @@ class PyDAG(PyDiGraph):
 
     .. jupyter-execute::
 
-        import rustworkx
+        import rustworkx as rx
 
-        graph = rustworkx.PyDAG()
+        graph = rx.PyDAG()
         data_payload = "An arbitrary Python object"
         node_index = graph.add_node(data_payload)
         graph[node_index] = "New Payload"
@@ -82,14 +82,14 @@ class PyDAG(PyDiGraph):
     performance, however you can enable it by setting the ``check_cycle``
     attribute to True. For example::
 
-        import rustworkx
-        dag = rustworkx.PyDAG()
+        import rustworkx as rx
+        dag = rx.PyDAG()
         dag.check_cycle = True
 
     or at object creation::
 
-        import rustworkx
-        dag = rustworkx.PyDAG(check_cycle=True)
+        import rustworkx as rx
+        dag = rx.PyDAG(check_cycle=True)
 
     With check_cycle set to true any calls to :meth:`PyDAG.add_edge` will
     ensure that no cycles are added, ensuring that the PyDAG class truly
@@ -107,8 +107,8 @@ class PyDAG(PyDiGraph):
     ``multigraph`` kwarg to ``False`` when calling the ``PyDAG`` constructor.
     For example::
 
-        import rustworkx
-        dag = rustworkx.PyDAG(multigraph=False)
+        import rustworkx as rx
+        dag = rx.PyDAG(multigraph=False)
 
     This can only be set at ``PyDiGraph`` initialization and not adjusted after
     creation. When :attr:`~rustworkx.PyDiGraph.multigraph` is set to ``False``
@@ -1951,7 +1951,7 @@ def bfs_search(graph, source, visitor):
 
     .. jupyter-execute::
 
-        import rustworkx
+        import rustworkx as rx
         from rustworkx.visit import BFSVisitor
 
 
@@ -1963,10 +1963,10 @@ def __init__(self):
             def tree_edge(self, edge):
                 self.edges.append(edge)
 
-        graph = rustworkx.PyDiGraph()
+        graph = rx.PyDiGraph()
         graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)])
         vis = TreeEdgesRecorder()
-        rustworkx.bfs_search(graph, [0], vis)
+        rx.bfs_search(graph, [0], vis)
         print('Tree edges:', vis.edges)
 
     .. note::
@@ -2033,7 +2033,7 @@ def dfs_search(graph, source, visitor):
 
     .. jupyter-execute::
 
-           import rustworkx
+           import rustworkx as rx
            from rustworkx.visit import DFSVisitor
 
            class TreeEdgesRecorder(DFSVisitor):
@@ -2044,10 +2044,10 @@ def __init__(self):
                def tree_edge(self, edge):
                    self.edges.append(edge)
 
-           graph = rustworkx.PyGraph()
+           graph = rx.PyGraph()
            graph.extend_from_edge_list([(1, 3), (0, 1), (2, 1), (0, 2)])
            vis = TreeEdgesRecorder()
-           rustworkx.dfs_search(graph, [0], vis)
+           rx.dfs_search(graph, [0], vis)
            print('Tree edges:', vis.edges)
 
     .. note::

rustworkx/visualization/graphviz.py

@@ -127,7 +127,7 @@ def graphviz_draw(
 
     .. jupyter-execute::
 
-        import rustworkx
+        import rustworkx as rx
         from rustworkx.visualization import graphviz_draw
 
         def node_attr(node):
@@ -138,7 +138,7 @@ def node_attr(node):
           else:
             return {'color': 'red', 'fillcolor': 'red', 'style': 'filled'}
 
-        graph = rustworkx.generators.directed_star_graph(weights=list(range(32)))
+        graph = rx.generators.directed_star_graph(weights=list(range(32)))
         graphviz_draw(graph, node_attr_fn=node_attr, method='sfdp')
 
     """