diff --git a/INSTALL.rst b/INSTALL.rst index f340f85767b2..ac24c70ac518 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -1,91 +1 @@ -############ -Installation -############ - -============================== -Installing an official release -============================== - -Matplotlib releases are available as wheel packages for macOS, Windows and -Linux on `PyPI `_. Install it using -``pip``: - -.. code-block:: sh - - python -m pip install -U pip - python -m pip install -U matplotlib - -If this command results in Matplotlib being compiled from source and -there's trouble with the compilation, you can add ``--prefer-binary`` to -select the newest version of Matplotlib for which there is a -precompiled wheel for your OS and Python. - -.. note:: - - The following backends work out of the box: Agg, ps, pdf, svg - - Python is typically shipped with tk bindings which are used by - TkAgg. - - For support of other GUI frameworks, LaTeX rendering, saving - animations and a larger selection of file formats, you can - install :ref:`optional_dependencies`. - -========================= -Third-party distributions -========================= - -Various third-parties provide Matplotlib for their environments. - -Conda packages -============== -Matplotlib is available both via the *anaconda main channel* - -.. code-block:: sh - - conda install matplotlib - -as well as via the *conda-forge community channel* - -.. code-block:: sh - - conda install -c conda-forge matplotlib - -Python distributions -==================== - -Matplotlib is part of major Python distributions: - -- `Anaconda `_ - -- `ActiveState ActivePython - `_ - -- `WinPython `_ - -Linux package manager -===================== - -If you are using the Python version that comes with your Linux distribution, -you can install Matplotlib via your package manager, e.g.: - -* Debian / Ubuntu: ``sudo apt-get install python3-matplotlib`` -* Fedora: ``sudo dnf install python3-matplotlib`` -* Red Hat: ``sudo yum install python3-matplotlib`` -* Arch: ``sudo pacman -S python-matplotlib`` - -====================== -Installing from source -====================== -See :ref:`install_from_source`. - -========================== -Installing for development -========================== -See :ref:`installing_for_devs`. - -============== -Installing FAQ -============== - -See :ref:`installing-faq`. +See doc/users/installing/index.rst diff --git a/README.rst b/README.rst index 5cd56c6ceaa1..a3ccbd6fcac8 100644 --- a/README.rst +++ b/README.rst @@ -58,8 +58,9 @@ various graphical user interface toolkits. Install ======= -For installation instructions and requirements, see `INSTALL.rst `_ or the -`install `_ documentation. +For installation instructions and requirements, see the `install documentation +`_ or +`installing.rst `_ in the source. Contribute ========== diff --git a/doc/conf.py b/doc/conf.py index 3a4e43c9a0f9..669957fe3ef4 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -212,8 +212,8 @@ def _check_dependencies(): # This is the default encoding, but it doesn't hurt to be explicit source_encoding = "utf-8" -# The master toctree document. -master_doc = 'users/index' +# The toplevel toctree document (renamed to root_doc in Sphinx 4.0) +root_doc = master_doc = 'users/index' # General substitutions. try: @@ -378,7 +378,7 @@ def _check_dependencies(): # document class [howto/manual]) latex_documents = [ - ('contents', 'Matplotlib.tex', 'Matplotlib', + (root_doc, 'Matplotlib.tex', 'Matplotlib', 'John Hunter\\and Darren Dale\\and Eric Firing\\and Michael Droettboom' '\\and and the matplotlib development team', 'manual'), ] @@ -461,6 +461,8 @@ def _check_dependencies(): # Additional stuff for the LaTeX preamble. latex_elements['preamble'] = r""" + % Show Parts and Chapters in Table of Contents + \setcounter{tocdepth}{0} % One line per author on title page \DeclareRobustCommand{\and}% {\end{tabular}\kern-\tabcolsep\\\begin{tabular}[t]{c}}% @@ -508,7 +510,7 @@ def _check_dependencies(): autoclass_content = 'both' texinfo_documents = [ - ("contents", 'matplotlib', 'Matplotlib Documentation', + (root_doc, 'matplotlib', 'Matplotlib Documentation', 'John Hunter@*Darren Dale@*Eric Firing@*Michael Droettboom@*' 'The matplotlib development team', 'Matplotlib', "Python plotting package", 'Programming', diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 76698a9a22d8..829fc73debf8 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -197,7 +197,7 @@ Documents can be linked with the ``:doc:`` directive: .. code-block:: rst - See the :doc:`/users/faq/installing_faq` + See the :doc:`/users/installing/index` See the tutorial :doc:`/tutorials/introductory/usage` @@ -205,14 +205,14 @@ Documents can be linked with the ``:doc:`` directive: will render as: - See the :doc:`/users/faq/installing_faq` + See the :doc:`/users/installing/index` See the tutorial :doc:`/tutorials/introductory/usage` See the example :doc:`/gallery/lines_bars_and_markers/simple_plot` Sections can also be given reference names. For instance from the -:doc:`/users/faq/installing_faq` link: +:doc:`/users/installing/index` link: .. code-block:: rst diff --git a/doc/users/faq/installing_faq.rst b/doc/users/faq/installing_faq.rst deleted file mode 100644 index c843da427f96..000000000000 --- a/doc/users/faq/installing_faq.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. _installing-faq: - -.. redirect-from:: /faq/installing_faq - -************** -Installing FAQ -************** - -.. contents:: - :backlinks: none - -Report a compilation problem -============================ - -See :ref:`reporting-problems`. - -Matplotlib compiled fine, but nothing shows up when I use it -============================================================ - -The first thing to try is a :ref:`clean install ` and see if -that helps. If not, the best way to test your install is by running a script, -rather than working interactively from a python shell or an integrated -development environment such as :program:`IDLE` which add additional -complexities. Open up a UNIX shell or a DOS command prompt and run, for -example:: - - python -c "from pylab import *; set_loglevel('debug'); plot(); show()" - -This will give you additional information about which backends Matplotlib is -loading, version information, and more. At this point you might want to make -sure you understand Matplotlib's :doc:`configuration ` -process, governed by the :file:`matplotlibrc` configuration file which contains -instructions within and the concept of the Matplotlib backend. - -If you are still having trouble, see :ref:`reporting-problems`. - -.. _clean-install: - -How to completely remove Matplotlib -=================================== - -Occasionally, problems with Matplotlib can be solved with a clean -installation of the package. In order to fully remove an installed Matplotlib: - -1. Delete the caches from your :ref:`Matplotlib configuration directory - `. - -2. Delete any Matplotlib directories or eggs from your :ref:`installation - directory `. - -OSX Notes -========= - -.. _which-python-for-osx: - -Which python for OSX? ---------------------- - -Apple ships OSX with its own Python, in ``/usr/bin/python``, and its own copy -of Matplotlib. Unfortunately, the way Apple currently installs its own copies -of NumPy, Scipy and Matplotlib means that these packages are difficult to -upgrade (see `system python packages`_). For that reason we strongly suggest -that you install a fresh version of Python and use that as the basis for -installing libraries such as NumPy and Matplotlib. One convenient way to -install Matplotlib with other useful Python software is to use the Anaconda_ -Python scientific software collection, which includes Python itself and a -wide range of libraries; if you need a library that is not available from the -collection, you can install it yourself using standard methods such as *pip*. -See the Ananconda web page for installation support. - -.. _system python packages: - https://github.com/MacPython/wiki/wiki/Which-Python#system-python-and-extra-python-packages -.. _Anaconda: https://www.anaconda.com/ - -Other options for a fresh Python install are the standard installer from -`python.org `_, or installing -Python using a general OSX package management system such as `homebrew -`_ or `macports `_. Power users on -OSX will likely want one of homebrew or macports on their system to install -open source software packages, but it is perfectly possible to use these -systems with another source for your Python binary, such as Anaconda -or Python.org Python. - -.. _install_osx_binaries: - -Installing OSX binary wheels ----------------------------- - -If you are using Python from https://www.python.org, Homebrew, or Macports, -then you can use the standard pip installer to install Matplotlib binaries in -the form of wheels. - -pip is installed by default with python.org and Homebrew Python, but needs to -be manually installed on Macports with :: - - sudo port install py38-pip - -Once pip is installed, you can install Matplotlib and all its dependencies with -from the Terminal.app command line:: - - python3 -mpip install matplotlib - -(``sudo python3.6 ...`` on Macports). - -You might also want to install IPython or the Jupyter notebook (``python3 -mpip -install ipython notebook``). - -Checking your installation --------------------------- - -The new version of Matplotlib should now be on your Python "path". Check this -at the Terminal.app command line:: - - python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)' - -You should see something like :: - - 3.0.0 /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/matplotlib/__init__.py - -where ``3.0.0`` is the Matplotlib version you just installed, and the path -following depends on whether you are using Python.org Python, Homebrew or -Macports. If you see another version, or you get an error like :: - - Traceback (most recent call last): - File "", line 1, in - ImportError: No module named matplotlib - -then check that the Python binary is the one you expected by running :: - - which python3 - -If you get a result like ``/usr/bin/python...``, then you are getting the -Python installed with OSX, which is probably not what you want. Try closing -and restarting Terminal.app before running the check again. If that doesn't fix -the problem, depending on which Python you wanted to use, consider reinstalling -Python.org Python, or check your homebrew or macports setup. Remember that -the disk image installer only works for Python.org Python, and will not get -picked up by other Pythons. If all these fail, please :ref:`let us know -`. diff --git a/doc/users/index.rst b/doc/users/index.rst index e065df00164b..9f913737af52 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -7,16 +7,6 @@ Users guide ########### -Tutorials and examples -###################### - -.. toctree:: - :maxdepth: 1 - - ../plot_types/index.rst - ../tutorials/index.rst - ../gallery/index.rst - General ####### @@ -29,6 +19,16 @@ General faq/index.rst resources/index.rst +Tutorials and examples +###################### + +.. toctree:: + :maxdepth: 1 + + ../plot_types/index.rst + ../tutorials/index.rst + ../gallery/index.rst + Reference ######### diff --git a/doc/users/installing/index.rst b/doc/users/installing/index.rst index 50c625bfcd83..10431d0cd465 100644 --- a/doc/users/installing/index.rst +++ b/doc/users/installing/index.rst @@ -1,10 +1,303 @@ -.. redirect-from:: /installing +.. redirect-from:: /users/installing +############ +Installation +############ -.. toctree:: - :hidden: +============================== +Installing an official release +============================== - installing_source.rst - ../faq/installing_faq.rst +Matplotlib releases are available as wheel packages for macOS, Windows and +Linux on `PyPI `_. Install it using +``pip``: -.. include:: ../../../INSTALL.rst +.. code-block:: sh + + python -m pip install -U pip + python -m pip install -U matplotlib + +If this command results in Matplotlib being compiled from source and +there's trouble with the compilation, you can add ``--prefer-binary`` to +select the newest version of Matplotlib for which there is a +precompiled wheel for your OS and Python. + +.. note:: + + The following backends work out of the box: Agg, ps, pdf, svg + + Python is typically shipped with tk bindings which are used by + TkAgg. + + For support of other GUI frameworks, LaTeX rendering, saving + animations and a larger selection of file formats, you can + install :ref:`optional_dependencies`. + +========================= +Third-party distributions +========================= + +Various third-parties provide Matplotlib for their environments. + +Conda packages +============== +Matplotlib is available both via the *anaconda main channel* + +.. code-block:: sh + + conda install matplotlib + +as well as via the *conda-forge community channel* + +.. code-block:: sh + + conda install -c conda-forge matplotlib + +Python distributions +==================== + +Matplotlib is part of major Python distributions: + +- `Anaconda `_ + +- `ActiveState ActivePython + `_ + +- `WinPython `_ + +Linux package manager +===================== + +If you are using the Python version that comes with your Linux distribution, +you can install Matplotlib via your package manager, e.g.: + +* Debian / Ubuntu: ``sudo apt-get install python3-matplotlib`` +* Fedora: ``sudo dnf install python3-matplotlib`` +* Red Hat: ``sudo yum install python3-matplotlib`` +* Arch: ``sudo pacman -S python-matplotlib`` + +.. redirect-from:: /users/installing/installing_source + +.. _install_from_source: + +====================== +Installing from source +====================== + +If you are interested in contributing to Matplotlib development, +running the latest source code, or just like to build everything +yourself, it is not difficult to build Matplotlib from source. + +First you need to install the :ref:`dependencies`. + +A C compiler is required. Typically, on Linux, you will need ``gcc``, which +should be installed using your distribution's package manager; on macOS, you +will need xcode_; on Windows, you will need Visual Studio 2015 or later. + +.. _xcode: https://guide.macports.org/chunked/installing.html#installing.xcode + +The easiest way to get the latest development version to start contributing +is to go to the git `repository `_ +and run:: + + git clone https://github.com/matplotlib/matplotlib.git + +or:: + + git clone git@github.com:matplotlib/matplotlib.git + +If you're developing, it's better to do it in editable mode. The reason why +is that pytest's test discovery only works for Matplotlib +if installation is done this way. Also, editable mode allows your code changes +to be instantly propagated to your library code without reinstalling (though +you will have to restart your python process / kernel):: + + cd matplotlib + python -m pip install -e . + +If you're not developing, it can be installed from the source directory with +a simple (just replace the last step):: + + python -m pip install . + +To run the tests you will need to install some additional dependencies:: + + python -m pip install -r requirements/dev/dev-requirements.txt + +Then, if you want to update your Matplotlib at any time, just do:: + + git pull + +When you run ``git pull``, if the output shows that only Python files have +been updated, you are all set. If C files have changed, you need to run ``pip +install -e .`` again to compile them. + +There is more information on :ref:`using git ` in the developer +docs. + +.. warning:: + + The following instructions in this section are for very custom + installations of Matplotlib. Proceed with caution because these instructions + may result in your build producing unexpected behavior and/or causing + local testing to fail. + +If you would like to build from a tarball, grab the latest *tar.gz* release +file from `the PyPI files page `_. + +We provide a `mplsetup.cfg`_ file which you can use to customize the build +process. For example, which default backend to use, whether some of the +optional libraries that Matplotlib ships with are installed, and so on. This +file will be particularly useful to those packaging Matplotlib. + +.. _mplsetup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/main/mplsetup.cfg.template + +If you are building your own Matplotlib wheels (or sdists) on Windows, note +that any DLLs that you copy into the source tree will be packaged too. + +========================== +Installing for development +========================== +See :ref:`installing_for_devs`. + +.. redirect-from:: /faq/installing_faq +.. redirect-from:: /users/faq/installing_faq + +.. _installing-faq: + +========================== +Frequently asked questions +========================== + +.. contents:: + :backlinks: none + :local: + +Report a compilation problem +============================ + +See :ref:`reporting-problems`. + +Matplotlib compiled fine, but nothing shows up when I use it +============================================================ + +The first thing to try is a :ref:`clean install ` and see if +that helps. If not, the best way to test your install is by running a script, +rather than working interactively from a python shell or an integrated +development environment such as :program:`IDLE` which add additional +complexities. Open up a UNIX shell or a DOS command prompt and run, for +example:: + + python -c "from pylab import *; set_loglevel('debug'); plot(); show()" + +This will give you additional information about which backends Matplotlib is +loading, version information, and more. At this point you might want to make +sure you understand Matplotlib's :doc:`configuration ` +process, governed by the :file:`matplotlibrc` configuration file which contains +instructions within and the concept of the Matplotlib backend. + +If you are still having trouble, see :ref:`reporting-problems`. + +.. _clean-install: + +How to completely remove Matplotlib +=================================== + +Occasionally, problems with Matplotlib can be solved with a clean +installation of the package. In order to fully remove an installed Matplotlib: + +1. Delete the caches from your :ref:`Matplotlib configuration directory + `. + +2. Delete any Matplotlib directories or eggs from your :ref:`installation + directory `. + +OSX Notes +========= + +.. _which-python-for-osx: + +Which python for OSX? +--------------------- + +Apple ships OSX with its own Python, in ``/usr/bin/python``, and its own copy +of Matplotlib. Unfortunately, the way Apple currently installs its own copies +of NumPy, Scipy and Matplotlib means that these packages are difficult to +upgrade (see `system python packages`_). For that reason we strongly suggest +that you install a fresh version of Python and use that as the basis for +installing libraries such as NumPy and Matplotlib. One convenient way to +install Matplotlib with other useful Python software is to use the Anaconda_ +Python scientific software collection, which includes Python itself and a +wide range of libraries; if you need a library that is not available from the +collection, you can install it yourself using standard methods such as *pip*. +See the Ananconda web page for installation support. + +.. _system python packages: + https://github.com/MacPython/wiki/wiki/Which-Python#system-python-and-extra-python-packages +.. _Anaconda: https://www.anaconda.com/ + +Other options for a fresh Python install are the standard installer from +`python.org `_, or installing +Python using a general OSX package management system such as `homebrew +`_ or `macports `_. Power users on +OSX will likely want one of homebrew or macports on their system to install +open source software packages, but it is perfectly possible to use these +systems with another source for your Python binary, such as Anaconda +or Python.org Python. + +.. _install_osx_binaries: + +Installing OSX binary wheels +---------------------------- + +If you are using Python from https://www.python.org, Homebrew, or Macports, +then you can use the standard pip installer to install Matplotlib binaries in +the form of wheels. + +pip is installed by default with python.org and Homebrew Python, but needs to +be manually installed on Macports with :: + + sudo port install py38-pip + +Once pip is installed, you can install Matplotlib and all its dependencies with +from the Terminal.app command line:: + + python3 -mpip install matplotlib + +(``sudo python3.6 ...`` on Macports). + +You might also want to install IPython or the Jupyter notebook (``python3 -mpip +install ipython notebook``). + +Checking your installation +-------------------------- + +The new version of Matplotlib should now be on your Python "path". Check this +at the Terminal.app command line:: + + python3 -c 'import matplotlib; print(matplotlib.__version__, matplotlib.__file__)' + +You should see something like :: + + 3.0.0 /Library/Frameworks/Python.framework/Versions/3.6/lib/python3.6/site-packages/matplotlib/__init__.py + +where ``3.0.0`` is the Matplotlib version you just installed, and the path +following depends on whether you are using Python.org Python, Homebrew or +Macports. If you see another version, or you get an error like :: + + Traceback (most recent call last): + File "", line 1, in + ImportError: No module named matplotlib + +then check that the Python binary is the one you expected by running :: + + which python3 + +If you get a result like ``/usr/bin/python...``, then you are getting the +Python installed with OSX, which is probably not what you want. Try closing +and restarting Terminal.app before running the check again. If that doesn't fix +the problem, depending on which Python you wanted to use, consider reinstalling +Python.org Python, or check your homebrew or macports setup. Remember that +the disk image installer only works for Python.org Python, and will not get +picked up by other Pythons. If all these fail, please :ref:`let us know +`. diff --git a/doc/users/installing/installing_source.rst b/doc/users/installing/installing_source.rst deleted file mode 100644 index bf635a0fdffb..000000000000 --- a/doc/users/installing/installing_source.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _install_from_source: - -====================== -Installing from source -====================== - -If you are interested in contributing to Matplotlib development, -running the latest source code, or just like to build everything -yourself, it is not difficult to build Matplotlib from source. - -First you need to install the :ref:`dependencies`. - -A C compiler is required. Typically, on Linux, you will need ``gcc``, which -should be installed using your distribution's package manager; on macOS, you -will need xcode_; on Windows, you will need Visual Studio 2015 or later. - -.. _xcode: https://guide.macports.org/chunked/installing.html#installing.xcode - -The easiest way to get the latest development version to start contributing -is to go to the git `repository `_ -and run:: - - git clone https://github.com/matplotlib/matplotlib.git - -or:: - - git clone git@github.com:matplotlib/matplotlib.git - -If you're developing, it's better to do it in editable mode. The reason why -is that pytest's test discovery only works for Matplotlib -if installation is done this way. Also, editable mode allows your code changes -to be instantly propagated to your library code without reinstalling (though -you will have to restart your python process / kernel):: - - cd matplotlib - python -m pip install -e . - -If you're not developing, it can be installed from the source directory with -a simple (just replace the last step):: - - python -m pip install . - -To run the tests you will need to install some additional dependencies:: - - python -m pip install -r requirements/dev/dev-requirements.txt - -Then, if you want to update your Matplotlib at any time, just do:: - - git pull - -When you run ``git pull``, if the output shows that only Python files have -been updated, you are all set. If C files have changed, you need to run ``pip -install -e .`` again to compile them. - -There is more information on :ref:`using git ` in the developer -docs. - -.. warning:: - - The following instructions in this section are for very custom - installations of Matplotlib. Proceed with caution because these instructions - may result in your build producing unexpected behavior and/or causing - local testing to fail. - -If you would like to build from a tarball, grab the latest *tar.gz* release -file from `the PyPI files page `_. - -We provide a `mplsetup.cfg`_ file which you can use to customize the build -process. For example, which default backend to use, whether some of the -optional libraries that Matplotlib ships with are installed, and so on. This -file will be particularly useful to those packaging Matplotlib. - -.. _mplsetup.cfg: https://raw.githubusercontent.com/matplotlib/matplotlib/master/mplsetup.cfg.template - -If you are building your own Matplotlib wheels (or sdists) on Windows, note -that any DLLs that you copy into the source tree will be packaged too.