DOC: fill out dev docs #9378

mattip · 2017-10-12T11:47:06Z

PR Summary

Trivial changeset to add more complete info for new devs getting started, fixes issue #9355

dstansby

Looks good overall, just a small change needed 👍

dstansby · 2017-10-12T17:28:08Z

doc/devel/testing.rst

@@ -20,6 +21,13 @@ infrastructure are in :mod:`matplotlib.testing`.
 Requirements
 ------------

+We strongly recommend developing new features in a seperate virtualenv.
+
+Install all the matplotlib dependencies_, and install matplotlib into the


"Matplotlib" should always be uppercase in the text.

jklymak · 2017-10-12T17:35:31Z

doc/devel/testing.rst

+We strongly recommend developing new features in a seperate virtualenv.
+
+Install all the matplotlib dependencies_, and install matplotlib into the
+virtualenv with ``pip install -e matplotlib`` (but note the changes needed to


OK, this isn't really my workflow. If you are developing, you need to pull down master from GitHub and pip install -e . from the GitHub directory. I also think that @anntzer just had a PR like this, or at least one that explicitly said how to pip install.

See #9291 and use of python -mpip install -e .

QuLogic · 2017-10-12T19:42:53Z

doc/devel/testing.rst

@@ -8,6 +8,7 @@ Matplotlib's testing infrastructure depends on pytest_. The tests are in
 :file:`lib/matplotlib/tests`, and customizations to the pytest testing
 infrastructure are in :mod:`matplotlib.testing`.

+.. _dependencies: http://matplotlib.org/users/installing.html#dependencies


This should be a Sphinx cross-references and not http://matplotlib.org/...

how do I do that to a particular anchor in the page, i.e. dependencies on the installing page?

You'd need to add a tag before the heading, but fortunately, there's already one there: install_requirements. You can use that name in the cross-reference instead of dependencies.

(This may be a bit difficult to find because doc/users/installing.html actually comes from INSTALL.rst in the top-level.)

So this change is not needed any more?

tacaswell · 2017-10-12T22:03:37Z

@mattip Thanks for doing this! Do you mind if I push some commits to your branch?

mattip · 2017-10-12T23:58:32Z

@tacaswell please go ahead

jklymak · 2017-10-13T05:04:41Z

doc/devel/testing.rst

+Install all the Matplotlib dependencies_, and install matplotlib into the
+virtualenv with ``pip install -e matplotlib`` (but note the changes needed to
+``setup.cfg`` below) which will allow you to edit the code without
+reinstalling.


I still think this is repeating what's in devel/contributing.rst. I think we should avoid duplicating instructions. If you haven't already installed the development version of Matplotlib then testing doesn't make a lot of sense.

I would just write "Install the latest version of Matplotlib as documented in http://matplotlib.org/devdocs/devel/contributing.html#retrieving-and-installing-the-latest-version-of-the-code. In particular, follow the instructions to use a local FreeType build." (fix the link, of course). And then remove the mention of localfreetype below.

(We also print a warning when tests are done on a nonlocal freetype version so I think that's enough.)

jklymak

Thanks this looks helpful!

mattip · 2017-10-17T13:52:10Z

@dstansby can you please review/approve?

dstansby · 2017-10-17T14:50:41Z

There's still a couple of places where 'Matplotlib' doesn't have an uppercase "M"; could you change them? Otherwise this looks good to go.

mattip · 2017-10-17T15:07:24Z

I pushed a changeset, but github is not responding?
@dstansby once you can see the changes, if I missed or overshot could you somehow mark them?

mattip · 2017-10-17T15:20:00Z

weird, I can see the changeset here on my fork but it is not triggering an update to the pull request

jklymak

Still missing lots of "matplotlib" -> "Matplotlib". A couple of small edits

jklymak · 2017-10-17T15:29:30Z

doc/devel/contributing.rst

+value.
+
+
+Install matplotlib in developer mode


Installing Matplotlib

jklymak · 2017-10-17T15:29:33Z

doc/devel/contributing.rst

+Unfortunately, different versions of FreeType produce differently
+formed characters, causing these image comparisons to fail.  To make
+them reproducible, matplotlib can be built with a special local copy
+of FreeType.  This is recommended for all matplotlib developers.


Matplotlib etc....

jklymak · 2017-10-17T15:29:35Z

doc/devel/contributing.rst

+meaning the result of a plot is compared against a known good result.
+Unfortunately, different versions of FreeType produce differently
+formed characters, causing these image comparisons to fail.  To make
+them reproducible, matplotlib can be built with a special local copy


jklymak · 2017-10-17T15:29:39Z

doc/devel/contributing.rst

-To make sure the tests run locally you must build against the correct version
-of freetype.  To configure the build system to fetch and build it either export
-the env ``MPLLOCALFREETYPE`` as::
+Building matplotlib for image comparison tests


jklymak · 2017-10-17T15:35:07Z

Oh, I see, you are having issues uploading! I thought your ability to search/replace "matplotlib" should have been better ;-) Sorry about that. Still suggest changing "Install" to "Installing" The rest fo the headings are "-ing"...

Was based on uploading issues

jklymak · 2017-10-17T17:32:32Z

You need to make sure your underlines extend the length of the titles....

dstansby · 2017-10-18T10:56:17Z

Looks like a nice improvement, thanks a lot!

Backport PR #9378 on branch v2.1.0-doc

fill out dev docs

60e9feb

dstansby added the Documentation label Oct 12, 2017

dstansby requested changes Oct 12, 2017

View reviewed changes

dstansby added this to the 2.1.0-docs milestone Oct 12, 2017

jklymak requested changes Oct 12, 2017

View reviewed changes

QuLogic reviewed Oct 12, 2017

View reviewed changes

document alternative to automatic download

1bf4450

jklymak reviewed Oct 13, 2017

View reviewed changes

mattip added 2 commits October 16, 2017 15:46

fixes from reviewers, failed CI, reshuffle FreeType section

753bed2

remove unneeded link

df0cdd0

jklymak approved these changes Oct 16, 2017

View reviewed changes

matplotlib to Matplotlib

680f178

jklymak previously requested changes Oct 17, 2017

View reviewed changes

add ..ing

c856d0c

dstansby approved these changes Oct 18, 2017

View reviewed changes

dstansby merged commit 401c1d7 into matplotlib:master Oct 18, 2017

lumberbot-app bot pushed a commit that referenced this pull request Oct 18, 2017

Backport PR #9378: DOC: fill out dev docs

02b434e

lumberbot-app bot mentioned this pull request Oct 18, 2017

Backport PR #9378 on branch v2.1.0-doc #9470

Merged

dopplershift added a commit that referenced this pull request Oct 18, 2017

Merge pull request #9470 from matplotlib/auto-backport-of-pr-9378

4552534

Backport PR #9378 on branch v2.1.0-doc

anntzer mentioned this pull request Oct 19, 2017

DOC: developer tips guide incomplete (for complete newbie) #9355

Closed

mattip deleted the devdocs branch February 15, 2018 23:07

Uh oh!

DOC: fill out dev docs #9378

DOC: fill out dev docs #9378

Uh oh!

Conversation

mattip commented Oct 12, 2017

PR Summary

Uh oh!

dstansby left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QuLogic Oct 15, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Oct 12, 2017

Uh oh!

mattip commented Oct 12, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jklymak left a comment

Choose a reason for hiding this comment

Uh oh!

mattip commented Oct 17, 2017

Uh oh!

dstansby commented Oct 17, 2017

Uh oh!

mattip commented Oct 17, 2017

Uh oh!

mattip commented Oct 17, 2017

Uh oh!

jklymak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jklymak commented Oct 17, 2017

Uh oh!

jklymak commented Oct 17, 2017

Uh oh!

dstansby commented Oct 18, 2017

Uh oh!

Uh oh!

QuLogic Oct 15, 2017 •

edited

Loading