Adding some FAQs

mdboom · mdboom · commit 68eba5600a85 · 2008-05-30T19:28:56.000Z
svn path=/trunk/matplotlib/; revision=5331
diff --git a/doc/faq/index.rst b/doc/faq/index.rst
@@ -12,5 +12,6 @@ Frequently asked questions about matplotlib
 .. toctree::
 
    installing_faq.rst
+   troubleshooting_faq.rst
    plotting_faq.rst
 
diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -1,7 +1,23 @@
-****************
-Installation FAQ
-****************
+==================
+ Installation FAQ
+==================
 
+How do I report a compilation problem?
+======================================
 
+See :ref:`reporting_problems`.
 
+How do I cleanly rebuild and reinstall everything?
+==================================================
 
+Unfortunately::
+
+    python setup.py clean
+
+does not properly clean the build directory, and does nothing to the
+install directory.  To cleanly rebuild:
+
+    * delete the ``build`` directory in the source tree 
+    * delete ``site-packages/matplotlib`` directory in the Python
+      installation.  The location of ``site-packages`` is
+      platform-specific.
diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst
@@ -0,0 +1,45 @@
+===================
+Troubleshooting FAQ
+===================
+
+.. _reporting_problems:
+
+How do I report a problem?
+==========================
+
+If you are having a problem with matplotlib, search the mailing
+lists first: There's a good chance someone else has already run into
+your problem.
+
+If not, please provide the following information in your e-mail to the
+mailing list:
+
+  * your operating system
+  * matplotlib version
+  * where you obtained matplotlib (e.g. your Linux distribution's
+    packages or the matplotlib Sourceforge site)
+  * any customizations to your ``matplotlibrc`` file
+  * if the problem is reproducible, please try to provide a minimal,
+    standalone Python script that demonstrates the problem
+
+If you compiled matplotlib yourself, please also provide 
+
+  * any changes you have made to ``setup.py`` or ``setupext.py``
+  * the output of::
+
+      rm -rf build
+      python setup.py build
+
+    The beginning of the build output contains lots of details about your
+    platform that are useful for the matplotlib developers to diagnose
+    your problem.  
+
+Including this information in your first e-mail to the mailing list
+will save a lot of time.
+
+You will likely get a faster response writing to the mailing list than
+filing a bug in the bug tracker.  Most developers check the bug
+tracker only periodically.  If your problem has been determined to be
+a bug and can not be quickly solved, you may be asked to file a bug in
+the tracker so the issue doesn't get lost.
+
