Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Many small fixes to ipython_directive.rst. #18

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 2 commits into from
Jul 26, 2017
Merged

Many small fixes to ipython_directive.rst. #18

merged 2 commits into from
Jul 26, 2017

Conversation

dhermes
Copy link
Contributor

@dhermes dhermes commented Jul 21, 2017

Including:

  • Typo fixes (e.g. "Sphinc" -> "Sphinx", "ruin" -> "run", etc.)
  • Python 3 errors with print used as a keyword vs. function
  • Changing line numbers to start at 1 locally within an ipython directive block (because they get renumbered anyhow)
  • Normalizing all usage of IPython and Sphinx (some places were lowercased, e.g. "ipython" and "sphinx")
  • Converting tabs to spaces (tabs seemed inadvertent)
  • Removing comments that have no effect on the block (output is only checked by doctest and only displayed during verbatim)
  • "Standardizing" the number of empty lines between sections
  • Adding whitespace between operators / commas (per PEP8)
  • Using implicit string concat rather than -continuation
  • Using codefont (via double backticks) for pseudo-decorator sections
  • Adding "Enabling IPython Directive" section which explains which Sphinx extensions enable this behavior

@dhermes
Many small fixes to ipython_directive.rst.
70f7888 
Including:

- Typo fixes (e.g. "Sphinc" -> "Sphinx", "ruin" -> "run", etc.)
- Python 3 errors with `print` used as a keyword vs. function
- Changing line numbers to start at 1 locally within an `ipython`
  directive block (because they get renumbered anyhow)
- Normalizing all usage of IPython and Sphinx (some places were
  lowercased, e.g. "ipython" and "sphinx")
- Converting tabs to spaces (tabs seemed inadvertent)
- Removing comments that have no effect on the block (output is
  only checked by `doctest` and only displayed during `verbatim`)
- "Standardizing" the number of empty lines between sections
- Adding whitespace between operators / commas (per PEP8)
- Using implicit string concat rather than \-continuation
- Using codefont (via double backticks) for pseudo-decorator sections
- Adding "Enabling IPython Directive" section which explains which
  Sphinx extensions enable this behavior
@dhermes
Copy link
Contributor Author

dhermes commented Jul 21, 2017

Worth noting: I found this document by reading the IPython.sphinxext.ipython_directive docstring

QuLogic
QuLogic reviewed Jul 21, 2017
View reviewed changes
ipython_directive.rst Outdated
for this document (see :ref:`ipython_literal`) because otherwise
you will see only the rendered output and not the code that
generated it. Excepting the example above, we will not in general
be showing the liuteral rest in this document that generates the
be showing the literal ReST in this document that generates the
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 reST.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

TIL! (Just checked https://en.wikipedia.org/wiki/ReStructuredText for "official" abbreviations.) Will update.

ipython_directive.rst
inserted, and prompts will be renumbered. So the prompt below should
be renumbered in the rendered docs, and pick up where the block above
left off.

.. ipython::

In [138]: z = x*3 # x is recalled from previous block
In [1]: z = x * 3 # x is recalled from previous block
Copy link
Member

Choose a reason for hiding this comment

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

Why is numbering restarting from 1 unlike the others?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

From my description

Changing line numbers to start at 1 locally within an ipython directive block (because they get renumbered anyhow)

Copy link
Member

Choose a reason for hiding this comment

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

Sure, but this seems to only have affected here and below, not the ones above. But I see now that that's just an example and not really the 136-th input line.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

There is only one block above (and one verbatim / <code> section so readers can see the block) and IIUC it's meant to support the opening text of this document:

The IPython directive is a stateful IPython shell for embedding in
Sphinx documents. It knows about standard IPython prompts, and
extracts the input and output lines. These prompts will be renumbered
starting at 1.

I'm happy to change it if you'd like, but ISTM that was the original author's intent.

ipython_directive.rst
File "<ipython console>", line 1
q = z[) # this is a syntax error -- we trap ipy exceptions
^
SyntaxError: invalid syntax
Copy link
Member

Choose a reason for hiding this comment

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

Is the traceback not captured any more?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It is captured, but this text was never rendered. I am happy to put the built HTML in a gist?

This was part of

Removing comments that have no effect on the block (output is only checked by doctest and only displayed during verbatim)

ipython_directive.rst Outdated
@@ -168,40 +139,39 @@ the inputs::
.. ipython::
:suppress:

In [144]: from pylab import *
In [1]: from pylab import *
Copy link
Member

Choose a reason for hiding this comment

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

pylab is dead; we should definitely remove this from any examples. Something more reasonable might be import numpy as np; import matplotlib.pyplot as plt.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

w00t! Happy to do that

@dhermes
PR review.
d1f837e 
- Updating "ReST" acronym / initialism to "reST"
- Dropping mention of `pylab` for "modern" `matplotlib`
@dhermes
Copy link
Contributor Author

dhermes commented Jul 25, 2017

Thanks @tacaswell. I don't have merge privileges, not sure if you do.

@tacaswell
Copy link
Member

I do, will let @QuLogic do one more pass.

@dhermes ps I know I still owe you a review on your JOSS paper

@dhermes
Copy link
Contributor Author

dhermes commented Jul 25, 2017 •
edited
Loading

PS Thanks for remembering @tacaswell 😀

@QuLogic QuLogic merged commit 6089101 into matplotlib:master Jul 26, 2017
@dhermes
Copy link
Contributor Author

dhermes commented Jul 26, 2017

Thanks for the merge!

@dhermes dhermes deleted the ipython-directive-fix branch July 26, 2017 16:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@QuLogic QuLogic QuLogic left review comments

@tacaswell tacaswell tacaswell approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@dhermes @tacaswell @QuLogic