X Tutup
Skip to content

Various documentation updates#8955

Merged
choldgraf merged 6 commits intomatplotlib:masterfrom
QuLogic:doc-updates
Jul 30, 2017
Merged

Various documentation updates#8955
choldgraf merged 6 commits intomatplotlib:masterfrom
QuLogic:doc-updates

Conversation

@QuLogic
Copy link
Copy Markdown
Member

@QuLogic QuLogic commented Jul 29, 2017

PR Summary

These are some minor preemptive corrections to the docs.

Firstly, import the unreleased What's New? entries into the docs so we can see what the output is like. There was one bug in there that I fixed. Unfortunately, Sphinx cannot see both a whats_new.rst file and a whats_new/ directory, so I had to rename one. I hope the instructions are reasonable for a release step @tacaswell.

Secondly, due to sphinx-gallery/sphinx-gallery#250, several things that were just printed out are now real Sphinx warnings, which will fail with our default build setup. I corrected the back-reference URLs so that sphinx-gallery stops warning and creates them now. Unfortunately, this does slow the build a bit, but I'm hoping sphinx-gallery/sphinx-gallery#272 can be merged as well to help with that.

Finally, with the deploy key added on CircleCI and devdocs, enable the new key so we can push the build docs on master. This should fix #8875. I have tested this on my fork and CircleCI correctly uploads docs once this change is made.

PR Checklist

  • [N/A] Has Pytest style unit tests
  • [N/A] Code is PEP 8 compliant
  • [N/A] New features are documented, with examples if plot related
  • Documentation is sphinx and numpydoc compliant
  • [N/A] Added an entry to doc/users/whats_new.rst if major new feature
  • [N/A] Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

@QuLogic QuLogic added this to the 2.1 (next point release) milestone Jul 29, 2017
@QuLogic QuLogic requested review from choldgraf and tacaswell July 29, 2017 02:47
QuLogic
QuLogic commented Jul 29, 2017
View reviewed changes
doc/users/whatsnew/multiple_legend_keys.rst

.. figure:: ../../gallery/pylab_examples/images/sphx_glr_legend_demo6_001.png
:target: ../../gallery/pylab_examples/legend_demo6.html
.. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_legend_demo_004.png
Copy link
Copy Markdown
Member Author

@QuLogic QuLogic Jul 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PS, @choldgraf for these, we don't need the ../.. because Sphinx accepts an absolute path. Unfortunately, it doesn't work on the target below though.

Copy link
Copy Markdown
Contributor

@choldgraf choldgraf Jul 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's good to know! thanks

@QuLogic
Copy link
Copy Markdown
Member Author

QuLogic commented Jul 29, 2017

Oops, I forgot the currently released version of sphinx-gallery doesn't support http:// links properly, so I reverted that bit. Hopefully should build now.

choldgraf
choldgraf reviewed Jul 29, 2017
View reviewed changes
doc/devel/release_guide.rst
----------

Before tagging, make sure that the docs build cleanly ::
Before tagging, update the what's new listing in :file:`doc/users/whats_new.rst`
Copy link
Copy Markdown
Contributor

@choldgraf choldgraf Jul 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it should be done in this PR, but I still think it'd be good to have some kind of "credit" system for various features. E.g. just making sure that every new feature or bugfix has a by XXX at the end, optionally with a link to a user webpage or something.

@choldgraf
Copy link
Copy Markdown
Contributor

choldgraf commented Jul 29, 2017

Almost all of this LGTM. The one thing I'm a little concerned about is having a whats_new.rst and a whatsnew folder. Why not call the folder whats_new_cache or something like that...so that it's clear it's a temporary holding place for new content that hasn't been incorporated into the main whats_new.rst file yet?

QuLogic added 6 commits July 29, 2017 22:32
@QuLogic
Rename doc/users/{whats_new => next_whats_new}/
087b18c 
This removes a conflict in Sphinx which can't see both the file and the
directory with the same name.
@QuLogic
Add 2.1 what's new into docs.
0e396e6 
This allows us to check that they're written correctly before getting
around to a release.
@QuLogic
Fix link to legend demo in what's new.
2e8817f
@QuLogic
Fix backreference URLs.
866691b
@QuLogic
Set SSH key to use for deployment.
7e97a37
@QuLogic
Skip deployment if not on Matplotlib org.
0c44435
@QuLogic
Copy link
Copy Markdown
Member Author

QuLogic commented Jul 30, 2017

I renamed it to next_whats_new to mirror the existing prev_whats_new directory. Also, reverted the change from https to http above as the latest release of sphinx-gallery is out now and supports https. With the new sphinx-gallery release, warnings are true warnings, so we do need to merge this soon-ish to fix that.

@tacaswell
Copy link
Copy Markdown
Member

tacaswell commented Jul 30, 2017

👍 doing that with the whats_new folder has been on my list of things to get to for a while!

@choldgraf
Copy link
Copy Markdown
Contributor

choldgraf commented Jul 30, 2017 •
edited
Loading

Then I say let's do it...tests are passing and I think the new folder naming works great

@choldgraf choldgraf merged commit 80a5e99 into matplotlib:master Jul 30, 2017
@choldgraf
Copy link
Copy Markdown
Contributor

choldgraf commented Jul 30, 2017

Thanks @QuLogic !!! 🎉

@QuLogic QuLogic deleted the doc-updates branch July 30, 2017 04:13
@QuLogic
Copy link
Copy Markdown
Member Author

QuLogic commented Jul 30, 2017

Fingers crossed on the deploy this time...

@QuLogic QuLogic mentioned this pull request Jul 30, 2017
Merged
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@choldgraf choldgraf choldgraf left review comments

@tacaswell tacaswell tacaswell approved these changes

Assignees

No one assigned

Labels

Documentation

Projects

None yet

Milestone

v2.1

Development

Successfully merging this pull request may close these issues.

uploading the devdocs is broken

3 participants

@QuLogic @choldgraf @tacaswell
X Tutup