Skip to content

Reorganize intro section on main page #16226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 30, 2020
Merged

Reorganize intro section on main page #16226

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions doc/_static/mpl.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1218,3 +1218,38 @@ hr.box-sep {
flex: 0 0 90%;
}
}

/* bullet boxes on main page */
div.bullet-box-container {
display: flex;
flex-wrap: wrap;
margin: 1em 0;
}

div.bullet-box {
flex-grow: 1;
width: 28%;
margin: 0.4em;
padding: 0 1em;
background: #eff9ff;
}

div.bullet-box p:first-of-type {
font-size: 1.4em;
text-align: center;
}

div.bullet-box ul {
padding-left: 1.2em;
}

div.bullet-box li {
padding-left: 0.3em;
margin-bottom: 0.3em;
}

@media only screen and (max-width: 930px){
div.bullet-box {
flex: 0 0 90%;
}
}
59 changes: 36 additions & 23 deletions doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,11 @@

.. title:: Matplotlib: Python plotting

Matplotlib is a Python 2D plotting library which produces publication quality
figures in a variety of hardcopy formats and interactive environments across
platforms. Matplotlib can be used in Python scripts, the Python and IPython_
shells, the Jupyter_ notebook, web application servers, and four graphical user
interface toolkits.
Matplotlib: Visualization with Python
-------------------------------------

.. _IPython: http://ipython.org
.. _Jupyter: http://jupyter.org
Matplotlib is a comprehensive library for creating static, animated,
and interactive visualizations in Python.

.. raw:: html

Expand All @@ -35,19 +32,41 @@ interface toolkits.
</div>
<span class="clear_screenshots"></span>

Matplotlib tries to make easy things easy and hard things possible. You
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally really like this sentence (yes, this specific wording) and would be sad to see it go -- it really embodies the matplotlib philsophy to me ("making hard things possible" is what distinguishes matplotlib from many "simpler" wrappers, and "making easy things easy" means that you don't have to fiddle with the GUI toolkit and that you can output to a bunch of formats natively, as opposed to e.g. web-only (js) libs).

Copy link
Member Author

@timhoffm timhoffm Jan 15, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand your point. I've thought for a while if I should keep this sentence.

TL;DR I don't think the sentence is helpful or even suitable. But if people are attached to it, I would be willing to leave it in for now.

I have three issues with it:

  • "Matplotlib tries to ..." is too defensive. In a philosophy you don't try. If anything this would need to be

    Matplotlib makes easy things easy and hard things possible.

  • Easy and hard things are highly vague and subjective.

    "making easy things easy" means that you don't have to fiddle with the GUI toolkit and that you can output to a bunch of formats natively, as opposed to e.g. web-only (js) libs

    is your particular interpretation and focused on the output aspect.
    I've read it more broadly as "Things that I can easily describe should be easy to code."

    In it's generality, you could apply the statement to a lot of software (It appears to coined on the design of Perl). It's not a distinctive feature of matplotlib. I assume that most of the visualization libraries would claim that paradigm (with different interpretations of easy and hard).

  • From a user perspective, IMHO we are not regarded as particularly easy for various reasons. It's partly because we see core matplotlib as fundamental building blocks, and we have a limited number of high-level helpers to arrange them. This is a design choice, which is perfectly fine. I just don't think we should over-emphasize easy.

    It's not easy if I need several lines of code to make a simple plot with axes labels, title and legend. It's not easy if I have to calculate positions for grouped bar charts. There are higher-level libraries that can claim "easy" much more.

Therefore, instead of "easy things easy and hard things possible", I hope to covey the two aspects more clearly and accurately with:

  • Easy creation of numerous standard plots
  • Customizable and extendable

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not going to try to argue rationally here -- it is strictly a sentimental attachment to this sentence. On the other hand, now that I stated my point, I'm not going to block its removal if there's agreement to do so.

(FWIW "Matplotlib makes easy things easy and hard things possible." is fine with me too, or perhaps "aims to ...".)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm with @anntzer on this - "Matplotlib makes easy things easy and hard things possible" is the brand/mission/ideal. And yes many users may not agree that we make easy things easy but this is the sales pitch. I think your text with some copy editing underneath works as an explanatory thing.

Copy link
Member Author

@timhoffm timhoffm Jan 15, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I would like to talk about the misson statement (and also this catch phrase) at some point. It is valuable to clarify that for ourselves and also to communicate it. - Will likely be a paragraph or two on a dedicated page.

For now, I've added the easy sentence back in.

can generate plots, histograms, power spectra, bar charts, errorcharts,
scatterplots, etc., with just a few lines of code. For examples, see the
:doc:`sample plots <tutorials/introductory/sample_plots>` and :doc:`thumbnail
gallery <gallery/index>`.
Matplotlib makes easy things easy and hard things possible.

For simple plotting the :mod:`.pyplot` module provides a MATLAB-like interface,
particularly when combined with IPython. For the power user, you have full
control of line styles, font properties, axes properties, etc, via an object
oriented interface or via a set of functions familiar to MATLAB users.
.. container:: bullet-box-container

.. container:: bullet-box

Create

- Develop `publication quality plots`_ with just with just a few lines of code
- Use `interactive figures`_ that can zoom, pan, update...

.. _publication quality plots: https://matplotlib.org/gallery/index.html
.. _interactive figures: https://matplotlib.org/gallery/index.html#event-handling

.. container:: bullet-box

Customize

- `Take full control`_ of line styles, font properties, axes properties...
- `Export and embed`_ to a number of file formats and interactive environments

.. _Take full control: https://matplotlib.org/tutorials/index.html#tutorials
.. _Export and embed: https://matplotlib.org/api/index_backend_api.html

.. container:: bullet-box

Extend

- Explore tailored functionality provided by
:doc:`third party packages <thirdpartypackages/index>`
- Learn more about matplotlib through the many
:doc:`external learning resources <resources/index>`

Documentation
-------------
~~~~~~~~~~~~~

This is the documentation for Matplotlib version |version|.

Expand Down Expand Up @@ -98,12 +117,6 @@ Trying to learn how to do a particular kind of plot? Check out the
:doc:`examples gallery <gallery/index>` or the :doc:`list of plotting commands
<api/pyplot_summary>`.

Other learning resources
~~~~~~~~~~~~~~~~~~~~~~~~

There are many :doc:`external learning resources <resources/index>` available
including printed material, videos and tutorials.

Join our community!
~~~~~~~~~~~~~~~~~~~

Expand Down