Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork7.9k
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
why can't you build docs locally? may be worth figuring it out... |
|
I thought maybe I had some cruft somewhere in my install, but a fresh git clone doesn't fix the issue. |
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 |
maybe I had too-old versions of the dependencies? Its still not building, but a fresh install of al the dependencies got me further... |
doc/devel/documenting_mpl.rst Outdated
| 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_) |
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.
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? |
Oh, sorry, resolved my building issues on gitter. I needed to do a |
Rebased after#9513 merged to master |
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 |
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 have ReST_ | ||
| 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!
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. |
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 tobfd225dCompareGiven 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. |
Hi all, I'd like to see this in for 2.2, so have marked as such. Thanks! |
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: