DOC: name not defined in section "2.14.1 Basic plotting: plot"

[gepcel]

In the pdf version of document, section "User Guide -> Visualization -> 2.14.1 Basic plotting: plot", page 588, there are name 'pd' (or 'ts') is not defined problems.

[MarcoGorelli]

Thanks @gepcel for the report - are you interested in submitting a pull request to fix this?

[gepcel]

Sure. I'd like to.

[gepcel]

I know this should be a very easy pr that should take less than one minute for an expert, but I need some guidance for something.

From what I understand, to fix this, I need to put some imports at the beginning of file visualization.rst. Which should be like:

.. _visualization:

{{ header }}

.. ipython:: python
   :suppress:

   import pandas as pd
   import numpy as np

   
*************
Visualization
*************

But what I don't understand is why some other files without the imports at the beginning are built without error, for example:

development/internals.rst

.. _internals:

{{ header }}

*********
Internals
*********

# A lot of stuff here and then

.. ipython:: python

   index = pd.MultiIndex.from_product(
       [range(3), ["one", "two"]], names=["first", "second"]
   )
   index
   index.levels
   index.codes
   index.names

[simonjayhawkins]

Thanks @gepcel for looking into this. I don't think any changes are needed to the documentation as the HTML pages are generated fine. https://pandas.pydata.org/docs/user_guide/visualization.html

The problem is in the pdf generation, where the header that includes imports is incorrectly generated. will look some more

[gepcel]

Some information somewhere gave me an impression that the header part {{header}} only applies to html format, not pdf.

[gepcel]

@simonjayhawkins It is actually weird that there is an {{ header }} before 2.14 Visualization, which indicates something is wrong with the header since the header do the pandas and numpy imports.

But compared with other chapters like groupby.rst:

The header in 'visualization.rst':

.. _visualization:

{{ header }}

*************
Visualization
*************

And the header in groupby.rst:

.. _groupby:

{{ header }}

*****************************
Group By: split-apply-combine
*****************************

There seems no difference here. And can someone help me what does .. currentmodule:: pandas mean, I have googled around with no result.

And there's another thing, due to the pdf documents, the header works fine in development/internals.rst with no error (page 2471 of pdf document).

But when I try to build the document for testing, there are errors:

D:\download\temp\pandas\doc>python make.py latex --no-api
Running Sphinx v3.2.1
making output directory... done
[autosummary] generating autosummary for: index.rst
building [mo]: targets for 0 po files that are out of date
building [latex]: all documents
updating environment: [new config] 144 added, 0 changed, 0 removed
reading sources... [  5%] development/internals

>>>-------------------------------------------------------------------------
Exception in D:\download\temp\pandas\doc\source\development\internals.rst at block ending on line 78
Specify :okexcept: as an option in the ipython:: block to suppress this message
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-1-6ad2af335eb8> in <module>
----> 1 index = pd.MultiIndex.from_product(
      2     [range(3), ["one", "two"]], names=["first", "second"]
      3 )

NameError: name 'pd' is not defined
<<<-------------------------------------------------------------------------

[gepcel]

Did some more research, I think the part doing the pre-imports for latex format is ipython_exec_lines, but not the {{ header }}. What I don't understand is:

1. Why the ipython_exec_lines works fine for most chapters but not this one?
2. Why does the {{ header }} line appear before 2.14 Visualization, but not other chapters?
3. What's the difference between the two types beginning of every chapter, sometimes there's .. currentmodule:: pandas and sometimes .. _indexing:?

[gepcel]

@jreback Before I understand the mechanism here, the only solution I know is to put the imports at the head of the chapter, like:

.. _visualization:

{{ header }}

.. ipython:: python
   :suppress:

   import pandas as pd
   import numpy as np

   
*************
Visualization
*************

I don't think this is the right solution because of the puzzles I mentioned before. I'll continue to dig and search around and test my ideas. Any help is appreciated. It's also fine by me for someone to take this over.

[simonjayhawkins]

The lastest uploaded PDF also has the problems in the visualization section.

for the release we do

./make.py html
./make.py zip_html
./make.py latex_forced ||:
./make.py latex_forced

I did manage to get the viz section to work, at some point, but IIRC other sections were corrupted.

I can't remember the order, maybe a clean and build the pdf before the html pages or maybe just run the ./make.py latex_forced once

so I don't think the docs need to change, but not sure why when we run ./make.py latex_forced the first time in the sequence above it chooses to only recreate (and corrupt) the viz section.

and IIRC running ./make.py latex_forced a few times more results in more corruption.

[gepcel]

I can't remember the order, maybe a clean and build the pdf before the html pages or maybe just run the ./make.py latex_forced once

I've set up developing environments with both windows 10 and ubuntu. Clean and build pdf before HTML pages with make.py latex_forced doesn't work.

The problem is the imports (both pd and np) didn't get imported at the beginning of the doc building. I have a guess:

During the HTML building, {{ header }} was put at every section with the jinja template mechanism, maybe generated some temporary files, and pdf building was based on those temporary files?