DOC: re-organize devel/documenting_mpl.rst #9884

jklymak · 2017-11-29T21:36:47Z

PR Summary

Latest build: https://5339-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/devel/documenting_mpl.html

This re-organizes doc/devel/documenting_mpl.rst. Some new content.

New suggested organization:

anntzer · 2017-11-29T23:50:58Z

why can't you build docs locally? may be worth figuring it out...

jklymak · 2017-11-29T23:51:32Z

AttributeError: 'BezierPath' object has no attribute '_draw_solid'

generating gallery for gallery/axisartist... [ 50%] demo_curvelinear_grid2.py
Exception occurred:
  File "/Users/jklymak/anaconda3/envs/matplotlibdev/lib/python3.6/site-packages/mpl_toolkits/axisartist/axis_artist.py", line 163, in draw
    lineFunc = getattr(self, funcname)
AttributeError: 'BezierPath' object has no attribute '_draw_solid'

jklymak · 2017-11-29T23:53:55Z

I thought maybe I had some cruft somewhere in my install, but a fresh git clone doesn't fix the issue.

jklymak · 2017-11-29T23:58:35Z

I do notice that somebody mucked around in that file in the last 11 months. But why its suddenly a problem for me, I'm not sure... #7771

jklymak · 2017-11-30T00:28:03Z

maybe I had too-old versions of the dependencies? Its still not building, but a fresh install of al the dependencies got me further...

anntzer · 2017-11-30T05:35:49Z

doc/devel/documenting_mpl.rst

-file name (the .rst extension is not necessary) in the table of contents.
-It is also possible to include other documents through the use of an include
-statement, such as::
+The documentation for Matplotlib is generated from reStructuredText (ReST_)


This part is also changed by #9513, which I'd prefer not to have to rebase again...

Cool this can wait for #9513 to be put in. I’m happy to rebase.

tacaswell · 2017-12-01T16:38:22Z

git clean -xfd can solve many problems!

The docs build against the installed version of Matplotlib so there is a lot of space for getting things crossed.

Can you run the example otherwise from a shell?

jklymak · 2017-12-01T16:44:34Z

Oh, sorry, resolved my building issues on gitter. I needed to do a conda remove --force matplotlib to clean out the original conda install matplotlib before doing pip installe -e .. I was getting old mpl_toolkit code somehow, which I don't usually get in my day-to-day testing.

jklymak · 2017-12-03T01:47:33Z

Rebased after #9513 merged to master

dstansby · 2017-12-04T20:37:52Z

https://4211-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/devel/documenting_mpl.html for anyone else who wants to review

dstansby

Looks good on the whole, just some small changes.

dstansby · 2017-12-04T20:39:24Z

doc/devel/documenting_mpl.rst

+
+Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from
+the docstrings of the classes in the Matplotlib library.  Except for
+:file:`doc/api/api_changes/`, these ``.rst`` are created when the


these .rst are created --> these .rst files are created

dstansby · 2017-12-04T20:41:09Z

doc/devel/documenting_mpl.rst

+Similarly, the contents of :file:`docs/gallery` and :file:`docs/tutorials` are
+generated by the `Sphinx Gallery`_ from the sources in :file:`examples` and
+:file:`tutorials`.  These sources consist of python scripts that have ReST_
+documentation built into their comments.  Again, don't directly edit the


This is the first time not editing .rst files is mentioned, maybe mention it earlier or get rid of "Again".

dstansby · 2017-12-04T20:44:02Z

doc/devel/documenting_mpl.rst

+Writing ReST pages
+==================
+
+As noted above, most documentation is either in the docstring of individual


Might be a personal style thing, but I'd get rid of "As noted above" since this page doesn't need to be read from start to end and people might just read bits and pieces.

Fair enough. Used to writing papers where half the reviewers will get mad at you if you repeat yourself, despite the fact people don't read papers very sequentially either ;-)

dstansby · 2017-12-04T20:44:26Z

doc/devel/documenting_mpl.rst

+Formatting and style conventions
+--------------------------------
+
+Its useful to strive for consistency in the Matplotlib documentation.  Here


Its --> It's

jklymak · 2017-12-04T20:55:46Z

Thanks a lot @dstansby I agree w/ all your changes.

I assume this is big enough that someone else should review, so I'll leave this alone until I get a second review.

jklymak · 2017-12-12T01:19:25Z

Changes made @dstansby

dstansby · 2018-01-10T12:45:34Z

doc/devel/documenting_mpl.rst

+
+  `matplotlib.collections.LineCollection`
+
+to get `matplotlib.collections.LineCollection`.  Its often not


"Its" --> "It's"

jklymak · 2018-01-13T16:11:56Z

Given that folks are making a good number of changes to the docs, I think it'd be nice if this were merged or closed if the re-org is not to people's taste. Note that I'm more than happy to wordsmith after, but rebases are hard given how much things have moved around.

jklymak · 2018-01-13T20:58:18Z

Latest: https://5339-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/devel/documenting_mpl.html

jklymak · 2018-01-19T16:59:57Z

Hi all, I'd like to see this in for 2.2, so have marked as such. Thanks!

dstansby · 2018-01-19T17:01:28Z

Okay, since this is only a doc change, and it doesn't delete anything, and I think it improves things, I'm going to merge it. We can always release doc-only updates faster than regular releases anyway.

jklymak force-pushed the doc-update-doc2 branch from 1df98ea to 4b6d852 Compare November 30, 2017 05:20

jklymak changed the title ~~WIP: Doc update doc2~~ Doc re-organize devel/documenting_mpl.rst Nov 30, 2017

jklymak changed the title ~~Doc re-organize devel/documenting_mpl.rst~~ DOC: re-organize devel/documenting_mpl.rst Nov 30, 2017

jklymak mentioned this pull request Nov 30, 2017

DOC: Minor enhancements to documenting_mpl #9872

Closed

6 tasks

anntzer reviewed Nov 30, 2017

View reviewed changes

jklymak added the Documentation label Nov 30, 2017

tacaswell added this to the v2.2 milestone Dec 1, 2017

jklymak force-pushed the doc-update-doc2 branch from 4b6d852 to d65740f Compare December 3, 2017 01:46

dstansby requested changes Dec 4, 2017

View reviewed changes

timhoffm mentioned this pull request Dec 9, 2017

The documentation on "how to write documentation" need to be updated #7217

Closed

jklymak force-pushed the doc-update-doc2 branch from d65740f to 1d58be3 Compare December 9, 2017 23:53

dstansby self-assigned this Dec 12, 2017

dstansby approved these changes Jan 10, 2018

View reviewed changes

DOC: re-organize documenting_mpl

bfd225d

jklymak force-pushed the doc-update-doc2 branch 2 times, most recently from 1f9d7c2 to bfd225d Compare January 13, 2018 16:09

jklymak added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Jan 19, 2018

dstansby merged commit 1f7a70d into matplotlib:master Jan 19, 2018

QuLogic modified the milestones: needs sorting, v2.2.0 Feb 12, 2018

jklymak deleted the doc-update-doc2 branch March 5, 2019 16:10

jklymak mentioned this pull request Jan 24, 2025

DOC: just new labels #29508

Open


		`matplotlib.collections.LineCollection`

		to get `matplotlib.collections.LineCollection`. Its often not

Uh oh!

DOC: re-organize devel/documenting_mpl.rst #9884

DOC: re-organize devel/documenting_mpl.rst #9884

Uh oh!

Conversation

jklymak commented Nov 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

anntzer commented Nov 29, 2017

Uh oh!

jklymak commented Nov 29, 2017

Uh oh!

jklymak commented Nov 29, 2017

Uh oh!

jklymak commented Nov 29, 2017

Uh oh!

jklymak commented Nov 30, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Dec 1, 2017

Uh oh!

jklymak commented Dec 1, 2017

Uh oh!

jklymak commented Dec 3, 2017

Uh oh!

dstansby commented Dec 4, 2017

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!

Choose a reason for hiding this comment

Uh oh!

jklymak commented Dec 4, 2017

Uh oh!

jklymak commented Dec 12, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jklymak commented Jan 13, 2018

Uh oh!

jklymak commented Jan 13, 2018

Uh oh!

jklymak commented Jan 19, 2018

Uh oh!

dstansby commented Jan 19, 2018

Uh oh!

Uh oh!

jklymak commented Nov 29, 2017 •

edited

Loading