From 390fc51804955181c46b260e4dfb3bf91b2729fd Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Tue, 16 Nov 2021 18:45:46 -0500 Subject: [PATCH 1/4] DOC: Fix toplevel LaTeX/Texinfo document This file was removed in #21251 --- doc/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 803f834898fc..cd9b8854f1f1 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'), ] @@ -508,7 +508,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', From c2eae8d5fda9c026abe9189dd1cef5df6f8d57ed Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Wed, 17 Nov 2021 19:24:30 -0500 Subject: [PATCH 2/4] DOC: Make chapters appear in PDF table of contents --- doc/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index cd9b8854f1f1..3311e73b046c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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}}% From a99ba43522c1983674167d0dab7abec08298885d Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Tue, 23 Nov 2021 03:32:55 -0500 Subject: [PATCH 3/4] Swap General and Tutorial/Example sections in User Guide This order seems to make more sense in the PDF, and it's probably okay in the webpage too. The end of the Quick start (which is the first page of General points to Installation, Plot types, and Tutorials, so you can navigate to those parts that used to be first quite easily. --- doc/users/index.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) 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 ######### From 9e0fe21cb1fac7611b431c370b83f2d17ba80f95 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Fri, 26 Nov 2021 03:45:22 -0500 Subject: [PATCH 4/4] Re-arrange installation doc layout This ensures that the ToC as generated in the PDF makes sense, and doesn't appear in the wrong order. Also fixes the redirect to come from the right place. --- INSTALL.rst | 92 +------ README.rst | 5 +- doc/devel/documenting_mpl.rst | 6 +- doc/users/faq/installing_faq.rst | 139 ---------- doc/users/installing/index.rst | 305 ++++++++++++++++++++- doc/users/installing/installing_source.rst | 76 ----- 6 files changed, 306 insertions(+), 317 deletions(-) delete mode 100644 doc/users/faq/installing_faq.rst delete mode 100644 doc/users/installing/installing_source.rst 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 70b0693a6251..7468d685f5d6 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/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/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 356558478a65..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/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.