DOC : whole bunch of documentation clean up #3170

tacaswell · 2014-06-30T03:24:55Z

No description provided.

tacaswell · 2014-06-30T03:27:18Z

To avoid clashing choas I am going to put all changes to rst files on this branch. People should do PRs against this one (or just yell at me) if you want things changed.

pelson · 2014-06-30T08:34:10Z

doc/faq/howto_faq.rst

+<https://github.com/matplotlib/matplotlib>`_.  If you would like
+to report a bug or submit a patch please use that interface.
+
+To report a bug (or request a feature) just `create an issue


I've never been a huge fan of using the issue tracker for feature requests, but I also don't really have a better idea (other than perhaps maintaining a second repo which is for feature-request issues only).

It is the most easily accessible tool for keeping track of/discussing changes to the code. It is unweildy to have many (very) old issues around. We should probably be better about closing things we really aren't going to implement. Maybe we should ask people to mail feature requests to the mailing list which get converted to issues when there is consensus they should be done (or some one just starts doing it).

When all you have is an issue tracker everthing looks like an issue....

To reinforce and extend this idea: I'm afraid there is a trend for people to go straight to the tracker with problems--not just feature requests--that really should be presented first on the list, so that a wider audience has a chance to answer questions.

pelson · 2014-06-30T08:39:53Z

Generally this is an excellent improvement. I'm of the opinion that the FAQ still needs some more work explaining the OO interface - but this is definitely a step in the right direction.

tacaswell · 2014-06-30T12:28:07Z

@pelson I agree it needs more work.

NelleV · 2014-07-02T17:49:52Z

doc/devel/coding_guide.rst

@@ -71,10 +72,35 @@ Documentation
  are not in that format.  We are working to standardize on
  `numpydoc`.

+  Docstrings should look like (at a minimum)::


Maybe add a link to the numpy doc format documentation?

There is already a link just out of the diff range

pelson · 2014-07-11T15:35:52Z

Please avoid putting other PRs against this PR. This PR is needlessly big and would be better as a collection of smaller PRs, but I appreciate that we are where we are with it.

tacaswell · 2014-07-11T16:36:08Z

I have been telling people to do pr s against this branch so that we avoid prose conflicts.

Maybe I should push this branch to the main repo so every one can the merging

NelleV · 2014-07-12T13:39:19Z

I'm happy with this PR, apart from the spelling mistake @pelson spotted.
There is room for improvement, but we can deal with this later.

NelleV · 2014-07-12T20:22:52Z

I am personally happy with this PR. I'm 👍 with merging.
There is room for improvements, but I think the changes should be incremental.

efiring · 2014-07-12T21:00:36Z

doc/devel/coding_guide.rst

+	      A description of foobaz
+          """
+	  # some very clever code
+	  return foobar, foobaz


I think this entire block above needs to be indented, doesn't it?

Sorry… Yes, it isn't aligned with "This" and "things"

turns out there were tabs in there....

efiring · 2014-07-12T21:23:36Z

I appreciate the effort, but I am not convinced that the changes to usage_faq.rst are a net improvement, as they stand. I would take this part out for now, or make only the most critical changes, such as changing the ipython option from -pylab to --pylab.

tacaswell · 2014-07-12T21:26:15Z

The consensus is that we are going to drop all reference to --pylab from our docs (the ipython team has already done so).

efiring · 2014-07-12T21:34:56Z

OK, then a little more change than I had hoped is needed in the usage_faq.rst, but still much less than is in the present version. Can't this be broken out into a separate PR? The present PR is a real monster.

As for dropping all references to --pylab, this might be premature, given its long history. A new "frequently-asked question" probably would be, "what about --pylab?". I suspect the net is full of examples and tutorials that invoke it. I think we need to explain something about what is going on with respect to its being relegated to the hall of shame, or to becoming "disappeared", rather like the way losers of political battles are treated in some countries.

- strengthen suggestion to use auto pep8 checker - added example minimal numpydoc docstring

- formatting - tweaked suggested imports to make copy-paste easier - updated list of versions of python

- github PR as primary mode of communication close matplotlib#2198

Added map of major parts of a figure

- changed some wording

- removed reference to pythonbrew (which has been deprecated) - moved tox section to very end as the docs and the tox file are both very out of date.

tacaswell · 2014-07-18T01:35:54Z

Rebased again. Someone who is not me needs to merge this.

efiring · 2014-07-18T01:41:17Z

doc/devel/coding_guide.rst

+                A description of foobar
+            foobaz : (type of foobaz)
+                A description of foobaz
+                """


Indentation of these triple quotes looks wrong.

fixed

On Thu, Jul 17, 2014 at 9:41 PM, Eric Firing notifications@github.com
wrote:

In doc/devel/coding_guide.rst:

Parameters

bar : (type of bar)

A description of bar

baz : (type of baz), optional

A description of baz

Returns

foobar : (type of foobar)

A description of foobar

foobaz : (type of foobaz)

A description of foobaz

"""

Indentation of these triple quotes looks wrong.

—
Reply to this email directly or view it on GitHub
https://github.com/matplotlib/matplotlib/pull/3170/files#r15093856.

Thomas Caswell
tcaswell@gmail.com

efiring · 2014-07-18T01:50:06Z

doc/faq/usage_faq.rst

+with the data space (marked as the inner blue box).  A given figure
+can contain many Axes, but a given :class:`~matplotlib.axes.Axes`
+object can only be in one :class:`~matplotlib.figure.Figure`.  The
+axes contains two (or three in the case of 3D)


Capitalize "Axes" here for consistency?

Fixed, I should probably squash all of these commits down.

efiring · 2014-07-18T02:01:22Z

doc/faq/usage_faq.rst

+includes :class:`Text` objects, :class:`Line2D` objects,
+:class:`collection` objects, :class:`Patch` objects ... (you get the idea).
+When the figure is rendered, all of the artists are drawn
+(recursively) to the **canvas**.  A given artist can only be in one


Delete the "(recursively)". I know what you mean, but this is not quite the right way to say it, and it doesn't need to be said here anyway. Also, suggested to replace "A given artist...":
"Most Artists are tied to an Axes; such an Artist cannot be shared by multiple Axes, or moved from one to another."

tacaswell · 2014-07-18T02:13:33Z

@efiring I think I have made all of the changes.

efiring · 2014-07-18T02:34:59Z

Do you want to squash it all down to one commit? I can merge it whenever you think it is ready.

efiring · 2014-07-18T02:40:34Z

Actually, why don't you just squash and rebase it on 1.4.x, merge, and then merge 1.4.x with master? It's reviewed. It doesn't preclude any additional changes once the docs are built with it.

tacaswell · 2014-07-18T02:59:12Z

Squasded and rebased onto 1.4.x (with out a merge commit) as 142435c . Merged into master as 5e07591

tacaswell added this to the v1.4.0 milestone Jun 30, 2014

tacaswell added doc labels Jun 30, 2014

tacaswell mentioned this pull request Jun 30, 2014

re-write contribution guide lines #2918

Closed

pelson reviewed Jun 30, 2014
View reviewed changes

NelleV reviewed Jul 2, 2014
View reviewed changes

tacaswell mentioned this pull request Jul 12, 2014

Fix lots of warnings in docs/Examples that crash #3224

Merged

efiring reviewed Jul 12, 2014
View reviewed changes

tacaswell added 14 commits July 17, 2014 21:34

DOC : removed reference to making a flash backend

0c85dfe

DOC : minor tweaks to coding_guide

050f3af

- strengthen suggestion to use auto pep8 checker - added example minimal numpydoc docstring

DOC : minor changes to docs

6cfccbf

- formatting - tweaked suggested imports to make copy-paste easier - updated list of versions of python

DOC : major work to development workflow docs

284135e

- github PR as primary mode of communication close matplotlib#2198

DOC : tweaked FAQ about new features

d11fc1a

DOC : added figure part diagram

9aa5f70

Added map of major parts of a figure

DOC : grammer fixes and doc edits

81e963b

- changed some wording

DOC : minor punctuation change

23a63da

DOC : removed reference to pylab on the front page

b1f0a60

DOC : minor edits

b21e34d

DOC : killed tabs with fire

5b613d4

DOC : changes to testing docs

ed65167

- removed reference to pythonbrew (which has been deprecated) - moved tox section to very end as the docs and the tox file are both very out of date.

DOC : minor rst markup fix

6d0503b

DOC : fix typo

a9b25e1

efiring reviewed Jul 18, 2014
View reviewed changes

DOC : minor indentation fix

6fcd723

efiring reviewed Jul 18, 2014
View reviewed changes

DOC : capitalization change

a26114d

efiring reviewed Jul 18, 2014
View reviewed changes

DOC : edits from efiring

19e8ad1

tacaswell closed this Jul 18, 2014

tacaswell deleted the howto_faq_cleanup branch August 28, 2014 03:03

QuLogic removed the status: needs review label Nov 24, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC : whole bunch of documentation clean up #3170

DOC : whole bunch of documentation clean up #3170

tacaswell commented Jun 30, 2014

tacaswell commented Jun 30, 2014

pelson Jun 30, 2014

tacaswell Jun 30, 2014

efiring Jul 1, 2014

pelson commented Jun 30, 2014

tacaswell commented Jun 30, 2014

NelleV Jul 2, 2014

tacaswell Jul 4, 2014

pelson commented Jul 11, 2014

tacaswell commented Jul 11, 2014

NelleV commented Jul 12, 2014

NelleV commented Jul 12, 2014

efiring Jul 12, 2014

NelleV Jul 12, 2014

NelleV Jul 12, 2014

tacaswell Jul 12, 2014

efiring commented Jul 12, 2014

tacaswell commented Jul 12, 2014

efiring commented Jul 12, 2014

tacaswell commented Jul 18, 2014

efiring Jul 18, 2014

tacaswell Jul 18, 2014

efiring Jul 18, 2014

tacaswell Jul 18, 2014

efiring Jul 18, 2014

tacaswell commented Jul 18, 2014

efiring commented Jul 18, 2014

efiring commented Jul 18, 2014

tacaswell commented Jul 18, 2014

DOC : whole bunch of documentation clean up #3170

DOC : whole bunch of documentation clean up #3170

Conversation

tacaswell commented Jun 30, 2014

tacaswell commented Jun 30, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pelson commented Jun 30, 2014

tacaswell commented Jun 30, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pelson commented Jul 11, 2014

tacaswell commented Jul 11, 2014

NelleV commented Jul 12, 2014

NelleV commented Jul 12, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

efiring commented Jul 12, 2014

tacaswell commented Jul 12, 2014

efiring commented Jul 12, 2014

tacaswell commented Jul 18, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Jul 18, 2014

efiring commented Jul 18, 2014

efiring commented Jul 18, 2014

tacaswell commented Jul 18, 2014