Clarify installation instructions so `pip install` works out of the box

[dan-zheng]

pip3 install python_graphs didn't work for me on macOS 13.5 (Apple Silicon) with Python 3.10:

$ pip3 install python_graphs
Collecting python_graphs
  Using cached python_graphs-1.2.3-py3-none-any.whl
Requirement already satisfied: absl-py in ./venv/lib/python3.10/site-packages (from python_graphs) (1.4.0)
Collecting astunparse (from python_graphs)
  Using cached astunparse-1.6.3-py2.py3-none-any.whl (12 kB)
Collecting gast (from python_graphs)
  Using cached gast-0.5.4-py3-none-any.whl (19 kB)
Requirement already satisfied: networkx in ./venv/lib/python3.10/site-packages (from python_graphs) (3.1)
Collecting pygraphviz (from python_graphs)
  Using cached pygraphviz-1.11.zip (120 kB)
  Preparing metadata (setup.py) ... done
Requirement already satisfied: six in ./venv/lib/python3.10/site-packages (from python_graphs) (1.16.0)
Requirement already satisfied: wheel<1.0,>=0.23.0 in ./venv/lib/python3.10/site-packages (from astunparse->python_graphs) (0.40.0)
Building wheels for collected packages: pygraphviz
  Building wheel for pygraphviz (setup.py) ... error
  error: subprocess-exited-with-error

  × python setup.py bdist_wheel did not run successfully.
  │ exit code: 1
  ╰─> [55 lines of output]
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build/lib.macosx-13-arm64-cpython-310
      creating build/lib.macosx-13-arm64-cpython-310/pygraphviz
      copying pygraphviz/scraper.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz
      copying pygraphviz/graphviz.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz
      copying pygraphviz/__init__.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz
      copying pygraphviz/agraph.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz
      copying pygraphviz/testing.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz
      creating build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_unicode.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_scraper.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_readwrite.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_string.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/__init__.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_html.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_node_attributes.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_drawing.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_repr_mimebundle.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_subgraph.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_close.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_edge_attributes.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_clear.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_layout.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_attribute_defaults.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      copying pygraphviz/tests/test_graph.py -> build/lib.macosx-13-arm64-cpython-310/pygraphviz/tests
      running egg_info
      writing pygraphviz.egg-info/PKG-INFO
      writing dependency_links to pygraphviz.egg-info/dependency_links.txt
      writing top-level names to pygraphviz.egg-info/top_level.txt
      reading manifest file 'pygraphviz.egg-info/SOURCES.txt'
      reading manifest template 'MANIFEST.in'
      warning: no files found matching '*.png' under directory 'doc'
      warning: no files found matching '*.txt' under directory 'doc'
      warning: no files found matching '*.css' under directory 'doc'
      warning: no previously-included files matching '*~' found anywhere in distribution
      warning: no previously-included files matching '*.pyc' found anywhere in distribution
      warning: no previously-included files matching '.svn' found anywhere in distribution
      no previously-included directories found matching 'doc/build'
      adding license file 'LICENSE'
      writing manifest file 'pygraphviz.egg-info/SOURCES.txt'
      copying pygraphviz/graphviz.i -> build/lib.macosx-13-arm64-cpython-310/pygraphviz
      copying pygraphviz/graphviz_wrap.c -> build/lib.macosx-13-arm64-cpython-310/pygraphviz
      running build_ext
      building 'pygraphviz._graphviz' extension
      creating build/temp.macosx-13-arm64-cpython-310
      creating build/temp.macosx-13-arm64-cpython-310/pygraphviz
      clang -Wno-unused-result -Wsign-compare -Wunreachable-code -fno-common -dynamic -DNDEBUG -g -fwrapv -O3 -Wall -isysroot /Library/Developer/CommandLineTools/SDKs/MacOSX13.sdk -DSWIG_PYTHON_STRICT_BYTE_CHAR -I/…/venv/include -I/opt/homebrew/opt/python@3.10/Frameworks/Python.framework/Versions/3.10/include/python3.10 -c pygraphviz/graphviz_wrap.c -o build/temp.macosx-13-arm64-cpython-310/pygraphviz/graphviz_wrap.o
      pygraphviz/graphviz_wrap.c:3020:10: fatal error: 'graphviz/cgraph.h' file not found
      #include "graphviz/cgraph.h"
               ^~~~~~~~~~~~~~~~~~~
      1 error generated.
      error: command '/opt/homebrew/bin/clang' failed with exit code 1
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for pygraphviz
  Running setup.py clean for pygraphviz
Failed to build pygraphviz
ERROR: Could not build wheels for pygraphviz, which is required to install pyproject.toml-based projects

The reason is pygraphviz has extra dependencies (graphviz) and special installation instructions.

_{https://pygraphviz.github.io/documentation/stable/install.html}

Figuring out the correct commands to install pygraphviz took quite a few minutes. Documenting this would be great.

[dan-zheng]

For reference, here are the pygraphviz installation instructions for macOS + Apple Silicon (for Apple Silicon, Homebrew has a custom install location):

$ brew install graphviz
$ pip3 install --use-pep517 \
            --config-setting="--global-option=build_ext" \
            --config-setting="--build-option=-I$(brew --prefix graphviz)/include/" \
            --config-setting="--build-option=-L$(brew --prefix graphviz)/lib/" \
            pygraphviz
$ pip3 install python_graphs  # Now this works

[dan-zheng]

I can help document these installation commands! We can just add a link to pygraphviz's installation commands.