Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork8.1k
DOC: re-organize devel/documenting_mpl.rst#9884
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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
anntzer commentedNov 29, 2017
why can't you build docs locally? may be worth figuring it out... |
jklymak commentedNov 29, 2017
|
jklymak commentedNov 29, 2017
I thought maybe I had some cruft somewhere in my install, but a fresh git clone doesn't fix the issue. |
jklymak commentedNov 29, 2017
I do notice thatsomebody mucked around in that file in the last 11 months. But why its suddenly a problem for me, I'm not sure...#7771 |
jklymak commentedNov 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... |
| file name (the.rst extension is not necessary) in the table of contents. | ||
| It is also possible toinclude other documents throughtheuse of an include | ||
| statement, such as:: | ||
| The documentation for Matplotlib is generated from reStructuredText (ReST_) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This part is also changed by#9513, which I'd prefer not to have to rebase again...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Cool this can wait for#9513 to be put in. I’m happy to rebase.
tacaswell commentedDec 1, 2017
The docs build against theinstalled version of Matplotlib so there is a lot of space for getting things crossed. Can you run the example otherwise from a shell? |
jklymak commentedDec 1, 2017
Oh, sorry, resolved my building issues on gitter. I needed to do a |
jklymak commentedDec 3, 2017
Rebased after#9513 merged to master |
dstansby commentedDec 4, 2017
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 left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Looks good on the whole, just some small changes.
doc/devel/documenting_mpl.rst Outdated
| 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
these.rst are created --> these.rst files are created
doc/devel/documenting_mpl.rst Outdated
| 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 haveReST_ | ||
| documentation built into their comments. Again, don't directly edit the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This is the first time not editing.rst files is mentioned, maybe mention it earlier or get rid of "Again".
doc/devel/documenting_mpl.rst Outdated
| Writing ReST pages | ||
| ================== | ||
| As noted above, most documentation is either in the docstring of individual |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 ;-)
doc/devel/documenting_mpl.rst Outdated
| Formatting and style conventions | ||
| -------------------------------- | ||
| Its useful to strive for consistency in the Matplotlib documentation. Here |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Its --> It's
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
-> It is!
jklymak commentedDec 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 commentedDec 12, 2017
Changes made@dstansby |
doc/devel/documenting_mpl.rst Outdated
| `matplotlib.collections.LineCollection` | ||
| to get `matplotlib.collections.LineCollection`. Its often not |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
"Its" --> "It's"
1f9d7c2 tobfd225dComparejklymak commentedJan 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 commentedJan 13, 2018
jklymak commentedJan 19, 2018
Hi all, I'd like to see this in for 2.2, so have marked as such. Thanks! |
dstansby commentedJan 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. |
Uh oh!
There was an error while loading.Please reload this page.
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: