Skip to content

Update docs on docs. #9311

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 1 commit into from
Nov 16, 2017
Merged

Update docs on docs. #9311

merged 1 commit into from
Nov 16, 2017

Conversation

anntzer
Copy link
Contributor

@anntzer anntzer commented Oct 7, 2017

Update PULL_REQUEST_TEMPLATE.md to emphasize markup specificities in RST
(as opposed to md) regarding double/single backquotes and asterisks.
(I'm a bit tired of pointing to this every other docstring PR.)

In documenting_mpl.rst:

  • Various reformattings/line wrappings/rewordings.
  • Explicitly mark the highlighting language of each code block, as we
    have a mix of python/shell/rst (and emacs lisp).
  • Drop unneeded :func:/:class: markups.
  • Drop request to line wrap docstrings at 70 characters (in practice
    they are line-wrapped at 79 like normal Python sources).
  • Do not forbid spanned cells in tables, which recent Sphinxes handles
    just fine.

In make.py:

  • Simplify argument parsing, slightly improving output of ./make.py --help

PR Summary

PR Checklist

  • Has Pytest style unit tests
  • Code is PEP 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

@dstansby
Copy link
Member

dstansby commented Oct 8, 2017

Would be good if someone could double check make.py..

@dstansby dstansby added this to the 2.1.0-docs milestone Oct 8, 2017
tacaswell
tacaswell reviewed Oct 8, 2017
View reviewed changes
.github/PULL_REQUEST_TEMPLATE.md Outdated
@@ -6,6 +6,12 @@ https://matplotlib.org/devdocs/devel/index.html-->
example "Raises ValueError on Non-Numeric Input to set_xlim". Please avoid
non-descriptive titles such as "Addresses issue #8576".-->

<!--If you are contributing fixes to docstrings
(which are very welcome!), please pay attention to
Copy link
Member

Choose a reason for hiding this comment

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

Can we make this less passive aggressive?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Feel free to propose an alternate wording 😃

Copy link
Member

Choose a reason for hiding this comment

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

I'm worried that the template is getting too large for anyone to bother reading - I'm happy to just get rid of (which are very welcome!) here,

@anntzer anntzer self-assigned this Oct 22, 2017
@anntzer
Copy link
Contributor Author

anntzer commented Oct 22, 2017

Temporarily closed to let #9513 be merged first.

@anntzer anntzer closed this Oct 22, 2017
@anntzer anntzer reopened this Nov 16, 2017
@anntzer anntzer mentioned this pull request Nov 16, 2017
Closed
@jklymak jklymak self-requested a review November 16, 2017 19:00
@anntzer anntzer removed their assignment Nov 16, 2017
dstansby
dstansby requested changes Nov 16, 2017
View reviewed changes
Copy link
Member

@dstansby dstansby left a comment

Choose a reason for hiding this comment

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

A couple of minor things, otherwise looks good to me!

doc/devel/documenting_mpl.rst
6. pillow
7. graphviz
6. Pillow
7. Graphviz
Copy link
Member

Choose a reason for hiding this comment

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

Needs sphinx-gallery

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Addressed in #9513.

doc/devel/documenting_mpl.rst
exist in the root directory. These contain Python files that are built by `Sphinx Gallery`_.
When the docs are built, directories of the same name will be generated inside of :file:`docs/`.
The generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted.
An exception to this are the directories :file:`gallery` and
Copy link
Member

Choose a reason for hiding this comment

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

Should be examples instead of gallery I think now?

Copy link
Contributor Author

@anntzer anntzer Nov 16, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

No, the files end up in the gallery subfolder of the source tree (and the build).

doc/devel/documenting_mpl.rst
:file:`tutorials`, which exist in the root directory. These contain Python
files that are built by `Sphinx Gallery`_. When the docs are built,
directories of the same name will be generated inside of :file:`docs/`. The
generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be
Copy link
Member

Choose a reason for hiding this comment

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

examples instead of gallery again here

.github/PULL_REQUEST_TEMPLATE.md Outdated
@@ -6,6 +6,12 @@ https://matplotlib.org/devdocs/devel/index.html-->
example "Raises ValueError on Non-Numeric Input to set_xlim". Please avoid
non-descriptive titles such as "Addresses issue #8576".-->

<!--If you are contributing fixes to docstrings
(which are very welcome!), please pay attention to
Copy link
Member

Choose a reason for hiding this comment

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

I'm worried that the template is getting too large for anyone to bother reading - I'm happy to just get rid of (which are very welcome!) here,

@anntzer
Update docs on docs.
37438af 
Update PULL_REQUEST_TEMPLATE.md to emphasize markup specificities in RST
(as opposed to md) regarding double/single backquotes and asterisks.

In documenting_mpl.rst:
- Various reformattings/line wrappings/rewordings.
- Explicitly mark the highlighting language of each code block, as we
  have a mix of python/shell/rst (and emacs lisp).
- Drop unneeded `:func:`/`:class:` markups.
- Drop request to line wrap docstrings at 70 characters (in practice
  they are line-wrapped at 79 like normal Python sources).
- Do not forbid spanned cells in tables, which recent Sphinxes handles
  just fine.

In make.py:
- Simplify argument parsing, slightly improving output of `./make.py
--help`
@anntzer
Copy link
Contributor Author

anntzer commented Nov 16, 2017

Removed the 'very welcome'.

@dstansby dstansby modified the milestones: v2.1.0-doc, v2.1.1 Nov 16, 2017
@jklymak
Copy link
Member

jklymak commented Nov 16, 2017

This looks fine to me. I was disappointed to still not see a description of how to reference functions both in MPL and using inter-sphinx. This is badly needed in my opinion. @dstansby does your PR address this?

@dstansby dstansby merged commit 4ed9996 into matplotlib:master Nov 16, 2017
@dstansby
Copy link
Member

It doesn't yet, but it can!

@lumberbot-app
Copy link

lumberbot-app bot commented Nov 16, 2017

There seem to be a conflict, please backport manually

@anntzer anntzer deleted the documenting-mpl branch November 16, 2017 23:39
@anntzer anntzer mentioned this pull request Nov 17, 2017
Merged
6 tasks
@tacaswell tacaswell modified the milestones: v2.1.1, v2.2 Dec 6, 2017
@tacaswell
Copy link
Member

re-milestoning this to 2.2. There is at least one other PR that did not get backported previously, the backport is not clean at all.

@QuLogic QuLogic modified the milestones: needs sorting, v2.2.0 Feb 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@tacaswell tacaswell tacaswell left review comments

@dstansby dstansby dstansby approved these changes

@jklymak jklymak Awaiting requested review from jklymak

Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v2.2.0
Development

Successfully merging this pull request may close these issues.
5 participants
@anntzer @dstansby @jklymak @tacaswell @QuLogic