DOC: Spellcheck of gotchas.rst (FAQ page) #19747

tommyod · 2018-02-18T09:59:15Z

Minor changes to the documentation, specifically gotchas.rst, i.e. the FAQ page.

Function/method references as links.
Consistent double backticks `` around Series, DataFrame.
Minor rephrasing of a sentence or two, added some missing punctuation.
Replaced .. ipython:: with ipython:: python twice, as the former is not sufficient to make the iPython code render in the docs.

Reviews/comments very welcome.

codecov · 2018-02-18T10:52:27Z

Codecov Report

Merging #19747 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #19747      +/-   ##
==========================================
- Coverage    91.6%    91.6%   -0.01%     
==========================================
  Files         150      150              
  Lines       48908    48864      -44     
==========================================
- Hits        44804    44763      -41     
+ Misses       4104     4101       -3

Flag	Coverage Δ
#multiple	`89.98% <ø> (-0.01%)`	⬇️
#single	`41.75% <ø> (-0.03%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/reshape/tile.py	`90.25% <0%> (-2.69%)`	⬇️
pandas/util/_decorators.py	`81.66% <0%> (-0.74%)`	⬇️
pandas/util/_validators.py	`96.34% <0%> (-0.47%)`	⬇️
pandas/core/ops.py	`96.45% <0%> (-0.32%)`	⬇️
pandas/core/indexes/datetimes.py	`95.32% <0%> (-0.25%)`	⬇️
pandas/core/indexes/range.py	`95.65% <0%> (-0.1%)`	⬇️
pandas/core/sparse/array.py	`91.38% <0%> (-0.09%)`	⬇️
pandas/core/indexes/timedeltas.py	`90.56% <0%> (-0.07%)`	⬇️
pandas/core/algorithms.py	`94.14% <0%> (-0.02%)`	⬇️
pandas/core/frame.py	`97.22% <0%> (-0.01%)`	⬇️
... and 15 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update abc4ef9...2b55328. Read the comment docs.

jreback · 2018-02-18T17:48:50Z

Replaced .. ipython:: with ipython:: python twice, as the former is not sufficient to make the iPython code render in the docs.

would welcome this an additional check in the lint.sh

jreback · 2018-02-18T17:49:36Z

doc/source/gotchas.rst


 .. ipython:: python

    dtypes = ['int64', 'float64', 'datetime64[ns]', 'timedelta64[ns]',
              'complex128', 'object', 'bool']
    n = 5000
-    data = dict([ (t, np.random.randint(100, size=n).astype(t))
+    data = dict([(t, np.random.randint(100, size=n).astype(t))
                    for t in dtypes])


can you fix indent here

jreback · 2018-02-18T17:49:45Z

doc/source/gotchas.rst

-specifies if the dataframe's memory usage will be displayed when
-invoking the ``df.info()`` method.
+The memory usage of a ``DataFrame`` (including the index) is shown when calling
+the :meth:`~DataFrame.info`. A configuration option, ``display.memory_usage`` 


can you reference this option directly?

jreback · 2018-02-18T17:51:00Z

doc/source/gotchas.rst

@@ -320,7 +323,7 @@ a different byte order than the one on which you are running Python. A common sy

 To deal
 with this issue you should convert the underlying NumPy array to the native
-system byte order *before* passing it to Series/DataFrame/Panel constructors
+system byte order *before* passing it to ``Series``/``DataFrame`` constructors


jorisvandenbossche · 2018-02-18T21:01:07Z

There are certain legitimate use cases of .. ipython:: blocks with the python added, so I am not sure we can add such a lint check in general.

jorisvandenbossche · 2018-02-18T21:06:55Z

For example, the code snippet here is done with a bar .. ipython:: on purpose: http://pandas.pydata.org/pandas-docs/stable/basics.html#iteritems. I don't recall exactly, but I think it was a problem with the for loop in a ipython::python directive (but it might be that that works correctly by now, but we would need to check).

jreback · 2018-02-22T02:07:59Z

ci/lint.sh

@@ -149,6 +149,15 @@ if [ "$LINT" ]; then
        RET=1
    fi
    echo "Check for deprecated messages without sphinx directive DONE"
+


does this pass now?

jreback · 2018-02-22T02:08:40Z

small question. looks fine. can you rebase and push again just to make sure.

jorisvandenbossche · 2018-02-22T10:32:23Z

@jreback no, this is not ready, see my comment

BTW, can you answer #19750 before merging this?

jorisvandenbossche · 2018-02-22T10:42:43Z

Ah, I didn't see that the CI was passing. But since we still have occurrences of .. ipython:: without python in our docs, that means the lint is check is actually not working?

tommyod · 2018-02-22T21:42:53Z

I believe this PR is good to go now.

Thanks for double-checking the lint @jorisvandenbossche. It seems like it was not working, glad you caught it. Since there might be cases which warrant .. ipython:: without python, I have removed the lint for now. In the particular case of the code blocks where I added python in this PR, the code is currently not rendered - so adding python seems correct as it now renders on my local doc build.

jreback · 2018-02-23T11:23:30Z

.. ipython:: without python

I guess, but why can't we cross this bridge i its actually needed. not-specifying python makes this look not so great and easy enough to avoid with a lint check.

jorisvandenbossche · 2018-02-23T11:39:11Z

The cases of .. ipython:: without python that @tommyod fixed, where indeed correct fixes (it were cases where we forgot this, and by forgetting it indeed did not render correctly in the docs).

But as I mentioned above, there are other cases where this was done on purpose (#19747 (comment)). And in those they are currently rendered fine. I am not sure if those cases are actually needed, but if someone wants to remove them, we should first check the docs build correctly without them.

jreback · 2018-02-23T11:45:49Z

ok that’s fine
better to have automatically checks in things if possible otherwise end up with inconsistencies over time

jreback added the Docs label Feb 18, 2018

jreback added this to the 0.23.0 milestone Feb 18, 2018

jreback requested changes Feb 18, 2018

View reviewed changes

jorisvandenbossche mentioned this pull request Feb 18, 2018

DOC: to quote or not to quote #19750

Open

jreback approved these changes Feb 22, 2018

View reviewed changes

tommyod added 5 commits February 22, 2018 21:44

Spellchecked gotchas.rst

22c3c94

Fixed some additional, minor spelling mistakes

9364732

Adressed comments. Added linting rule.

54aebc9

Fixed indentation in lint.sh

5b29136

Removed lint for '.. python:' without python

2b55328

jreback merged commit 0176f6e into pandas-dev:master Feb 23, 2018

harisbal pushed a commit to harisbal/pandas that referenced this pull request Feb 28, 2018

DOC: Spellcheck of gotchas.rst (FAQ page) (pandas-dev#19747)

4242a0e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Spellcheck of gotchas.rst (FAQ page) #19747

DOC: Spellcheck of gotchas.rst (FAQ page) #19747

tommyod commented Feb 18, 2018

codecov bot commented Feb 18, 2018 •

edited

Loading

jreback commented Feb 18, 2018

jreback Feb 18, 2018

jreback Feb 18, 2018

jreback Feb 18, 2018

jorisvandenbossche commented Feb 18, 2018

jorisvandenbossche commented Feb 18, 2018

jreback Feb 22, 2018

jreback commented Feb 22, 2018

jorisvandenbossche commented Feb 22, 2018

jorisvandenbossche commented Feb 22, 2018

tommyod commented Feb 22, 2018

jreback commented Feb 23, 2018

jorisvandenbossche commented Feb 23, 2018

jreback commented Feb 23, 2018

DOC: Spellcheck of gotchas.rst (FAQ page) #19747

DOC: Spellcheck of gotchas.rst (FAQ page) #19747

Conversation

tommyod commented Feb 18, 2018

codecov bot commented Feb 18, 2018 • edited Loading

Codecov Report

jreback commented Feb 18, 2018

jreback Feb 18, 2018

Choose a reason for hiding this comment

jreback Feb 18, 2018

Choose a reason for hiding this comment

jreback Feb 18, 2018

Choose a reason for hiding this comment

jorisvandenbossche commented Feb 18, 2018

jorisvandenbossche commented Feb 18, 2018

jreback Feb 22, 2018

Choose a reason for hiding this comment

jreback commented Feb 22, 2018

jorisvandenbossche commented Feb 22, 2018

jorisvandenbossche commented Feb 22, 2018

tommyod commented Feb 22, 2018

jreback commented Feb 23, 2018

jorisvandenbossche commented Feb 23, 2018

jreback commented Feb 23, 2018

codecov bot commented Feb 18, 2018 •

edited

Loading