DOC:Add link to style examples in matplotlib.style documentation

[sameshl]

The documentation for matplotlib.style isn't very helpful for those wanting to use a style sheet, so added reference to stylesheet references.

PS: I messed up the commit history of my previous PR on the same issue, so made a new PR.
closes #14362

PR Summary

PR Checklist

• Has Pytest style unit tests
• Code is Flake 8 compliant
• New features are documented, with examples if plot related
• Documentation is sphinx and numpydoc compliant
• Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
• Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

[sameshl]

@timhoffm Can you help me understand why the tests are failing on circleci?

[timhoffm]

If you check the CircleCI output, you'll find

/home/circleci/project/doc/api/style_api.rst:21: WARNING: undefined label: style_sheets_reference (if the link has no caption the label must precede a section header)

If you then check style_sheets_reference.rst, you'll notice that the heading has a label defined:

.. _sphx_glr_gallery_style_sheets_style_sheets_reference.py:

That would be the right one to use (see also https://matplotlib.org/devel/documenting_mpl.html?highlight=writing%20documentation#referring-to-other-documents-and-sections).

However, in this context I would reference the whole document by using

:doc:`/gallery/style_sheets/style_sheets_reference`

The difference is

• ref: https://matplotlib.org/gallery/style_sheets/style_sheets_reference.html#style-sheets-reference
• doc: https://matplotlib.org/gallery/style_sheets/style_sheets_reference.html

As an exercise, you can git commit --amend this change followed by git push origin update_style_documentation --force 😄.

[sameshl]

@timhoffm Thank you so much for all the info. It feels so great to contribute to an organization which help you improve 😄 . Would love to continue contributing here!

[timhoffm]

Rendered docs: https://23056-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/style_api.html

Now that I'm looking at it, would it make sense to put this above the API description? This is a bit lost at the bottom of the page. I'm afraid nobody will see it.

[sameshl]

@timhoffm I agree. It would be better if I place it above the api description with a one-liner info.
Going a bit offtopic, but I had two questions:

1. I don't have doc/gallery/style_sheets/style_sheets_reference.py file on my local clone of this repo. In fact I don't have doc/gallery/style_sheets/ folder itself. Is it because I did not make docs locally?
2. How did you navigate to rendered docs link? I am unable to find the link when I go to circleci build logs

[jklymak]

https://circleci.com/gh/matplotlib/matplotlib/23056?utm_campaign=vcs-integration-link&utm_medium=referral&utm_source=github-build-link

under "Built documentation is available at..."

[tacaswell]

and to answer question 1) Yes, they are copied around as part of the doc building process. The source lives at https://github.com/matplotlib/matplotlib/blob/master/examples/style_sheets/style_sheets_reference.py

[sameshl]

@timhoffm Made the change. Looks much better now

[jklymak]

"Examples of..."

Is there some reason this needs a "seealso"?

Is there any reason to not be even a bit more verbose here? I don't find the style sheet reference example particularly helpful either. I'd suggest pointing to the style sheet section of the examples rather than the master reference. And if you really want to make it nice, I'd include a bit more detail. i.e.

Matplotlib has the ability to make style sheets that control the default values of variables in the matplotlibrc (see plt.rcParam) that control how plot elements look.  Style sheets allow different parts of a script to have different styles using the `styles.use('mystyle')` call. Users can also define their own custom styles and store them in their `.matplotlib` directory.  

Or something like that. I'm a little surprised we don't already have anything like that.

If you don't feel like tackling that here, thats fine, this is an improvement as-is (except for the typo), and we could open a new issue about being more verbose here..

[sameshl]

I understand. I think I could fix this typo and work on giving more detail in a separate PR.

[jklymak]

Thanks @sameshl !

[sameshl]

@jklymak Looking forward to make more contributions here! 😃