Skip to content

Various documentation updates #8955

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 6 commits into from
Jul 30, 2017
Merged

Various documentation updates #8955

merged 6 commits into from
Jul 30, 2017

Conversation

QuLogic
Copy link
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 tacaswell and choldgraf July 29, 2017 02:47
QuLogic
QuLogic commented Jul 29, 2017
View reviewed changes
doc/users/whatsnew/multiple_legend_keys.rst Outdated
@@ -6,11 +6,9 @@ A legend entry can now contain more than one legend key. The extended
legend area in the specified number of sections; ``pad`` changes the padding
between the legend keys.

.. 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
Member Author

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
Contributor

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
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
@@ -48,7 +48,10 @@ Review and commit changes. Some issue/PR titles may not be valid rst (the most
Check Docs
----------

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
Contributor

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
Contributor

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
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
Member

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

@choldgraf
Copy link
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
Contributor

Thanks @QuLogic !!! 🎉

@QuLogic QuLogic deleted the doc-updates branch July 30, 2017 04:13
@QuLogic
Copy link
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