Skip to content
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.

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

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

Merged
merged 1 commit into from Jan 19, 2018

Conversation

Projects
None yet
5 participants
@jklymak
Copy link
Contributor

commented Nov 29, 2017

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:

banners_and_alerts_and_writing_documentation_ _matplotlib_2_1_0_post923_dev0_g1df98ea82_documentation

@anntzer

This comment has been minimized.

Copy link
Contributor

commented Nov 29, 2017

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

@jklymak

This comment has been minimized.

Copy link
Contributor Author

commented Nov 29, 2017

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

This comment has been minimized.

Copy link
Contributor Author

commented Nov 29, 2017

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

@jklymak

This comment has been minimized.

Copy link
Contributor Author

commented Nov 29, 2017

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

This comment has been minimized.

Copy link
Contributor Author

commented Nov 30, 2017

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

@jklymak jklymak force-pushed the jklymak:doc-update-doc2 branch from 1df98ea to 4b6d852 Nov 30, 2017

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

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

@jklymak jklymak referenced this pull request Nov 30, 2017

Closed

DOC: Minor enhancements to documenting_mpl #9872

0 of 6 tasks complete
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 comment has been minimized.

Copy link
@anntzer

anntzer Nov 30, 2017

Contributor

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

This comment has been minimized.

Copy link
@jklymak

jklymak Nov 30, 2017

Author Contributor

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

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

@tacaswell

This comment has been minimized.

Copy link
Member

commented Dec 1, 2017

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

This comment has been minimized.

Copy link
Contributor Author

commented Dec 1, 2017

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 jklymak force-pushed the jklymak:doc-update-doc2 branch from 4b6d852 to d65740f Dec 3, 2017

@jklymak

This comment has been minimized.

Copy link
Contributor Author

commented Dec 3, 2017

Rebased after #9513 merged to master

@dstansby

This comment has been minimized.

@dstansby
Copy link
Contributor

left a comment

Looks good on the whole, just some small changes.


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

This comment has been minimized.

Copy link
@dstansby

dstansby Dec 4, 2017

Contributor

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

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 comment has been minimized.

Copy link
@dstansby

dstansby Dec 4, 2017

Contributor

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

Writing ReST pages
==================

As noted above, most documentation is either in the docstring of individual

This comment has been minimized.

Copy link
@dstansby

dstansby Dec 4, 2017

Contributor

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.

This comment has been minimized.

Copy link
@jklymak

jklymak Dec 9, 2017

Author Contributor

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 ;-)

Formatting and style conventions
--------------------------------

Its useful to strive for consistency in the Matplotlib documentation. Here

This comment has been minimized.

Copy link
@dstansby

dstansby Dec 4, 2017

Contributor

Its --> It's

This comment has been minimized.

Copy link
@jklymak

jklymak Dec 9, 2017

Author Contributor

-> It is!

@jklymak

This comment has been minimized.

Copy link
Contributor Author

commented Dec 4, 2017

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

This comment has been minimized.

Copy link
Contributor Author

commented Dec 12, 2017

Changes made @dstansby

@dstansby dstansby self-assigned this Dec 12, 2017

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

This comment has been minimized.

Copy link
@dstansby

dstansby Jan 10, 2018

Contributor

"Its" --> "It's"

@jklymak jklymak force-pushed the jklymak:doc-update-doc2 branch 2 times, most recently from 1f9d7c2 to bfd225d Jan 13, 2018

@jklymak

This comment has been minimized.

Copy link
Contributor Author

commented Jan 13, 2018

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

This comment has been minimized.

@jklymak

This comment has been minimized.

Copy link
Contributor Author

commented Jan 19, 2018

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

@dstansby

This comment has been minimized.

Copy link
Contributor

commented Jan 19, 2018

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.

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

8 checks passed

ci/circleci: docs-python27 Your tests passed on CircleCI!
Details
ci/circleci: docs-python35 Your tests passed on CircleCI!
Details
codecov/patch Coverage not affected when comparing 3bb328f...bfd225d
Details
codecov/project/library 63.68% (target 50%)
Details
codecov/project/tests 98.85% remains the same compared to 3bb328f
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
lgtm analysis: Python No alert changes
Details

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

@jklymak jklymak deleted the jklymak:doc-update-doc2 branch Mar 5, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.