DOC: add back currentmodule to api.rst

[jorisvandenbossche]

xref #24191

@datapythonista I don't understand why, but the .. currentmodule:: pandas does not seem to be picked up from header.rst, giving extra warnings and missing links (because in api.rst, everything up to the first inline currentmodule, is not found)

See eg http://pandas-docs.github.io/pandas-docs-travis/api.html, only from json there are actual links.

[jorisvandenbossche]

What makes it even stranger is that 10min.rst is build before api.rst, and there it is actually fine (the :class:`Series` links work for example)

[datapythonista]

I'm missing a bit of content here, not sure where the extra warnings are, but there is something tricky with this:

• When the .rst are processed with sphinx, {header} becomes the imports and the current module, and everything should be all right
• When the .rst files are processed with something else (e.g. flake8-rst, validate_docstrings.py), {header} is never rendered, and we need to add extra stuff (for example, in flake8-rst we have a bootstrap setting in setup.cfg

That being said, can you merge the latest master? Because we had a problem with the validate_docstrings.py failing to list all items in api.rst because it was lacking the current module. That was already fixed, not sure if that's what you saw.

[datapythonista]

Oh, sorry, I understood now, didn't get the problem with the links. Seems like a bug in sphinx then?

[jorisvandenbossche]

I'm missing a bit of context here, not sure where the extra warnings are

Did you see the link to the dev docs with the non-working links?

The warnings in the doc build are fully at the beginning:

WARNING: [autosummary] failed to import 'DataFrame.to_sql': no module named DataFrame.to_sql
WARNING: [autosummary] failed to import 'ExcelFile.parse': no module named ExcelFile.parse
WARNING: [autosummary] failed to import 'ExcelWriter': no module named ExcelWriter
WARNING: [autosummary] failed to import 'read_clipboard': no module named read_clipboard
WARNING: [autosummary] failed to import 'read_csv': no module named read_csv
WARNING: [autosummary] failed to import 'read_excel': no module named read_excel
WARNING: [autosummary] failed to import 'read_fwf': no module named read_fwf
WARNING: [autosummary] failed to import 'read_json': no module named read_json
WARNING: [autosummary] failed to import 'read_msgpack': no module named read_msgpack
WARNING: [autosummary] failed to import 'read_pickle': no module named read_pickle
WARNING: [autosummary] failed to import 'read_sql': no module named read_sql
WARNING: [autosummary] failed to import 'read_sql_query': no module named read_sql_query
WARNING: [autosummary] failed to import 'read_sql_table': no module named read_sql_table
WARNING: [autosummary] failed to import 'read_table': no module named read_table

and all at the end:

b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.read_table'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.read_csv'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.read_fwf'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.read_msgpack'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.read_clipboard'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.read_excel'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.ExcelFile.parse'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.ExcelWriter'
b'<partial node>':: WARNING: toctree contains reference to nonexisting document 'generated/pandas.read_json'
...
(many more)

That being said, can you merge the latest master? Because we had a problem with the validate_docstrings.py failing to list all items in api.rst because it was lacking the current module. That was already fixed, not sure if that's what you saw.

This is with latest master, and has nothing to do with validate_docstrings, but with the actual sphinx build.

[jorisvandenbossche]

Seems like a bug in sphinx then?

Yeah, not sure. It might be, but I don't understand why it works for the references, but not for autosummary.

[jorisvandenbossche]

Yeah, not sure. It might be, but I don't understand why it works for the references, but not for autosummary.

Ah, maybe because autosummary is ran before the inserts are done? Do you know when the {{ header }} gets processed?

[datapythonista]

makes sense

Happy to have the current module in api.rst, but I'd add a comment why we do, so we don't have the temptation to remove it in the future

[jorisvandenbossche]

Yes, took a short dive into sphinx .. :-), and it is indeed because the autosummary generation happens before reading the files.
The connect the event to generate all autodoc files to the build-init (so before the source-read event):

https://github.com/sphinx-doc/sphinx/blob/af87e026e37433572b07a5332b257cb8436510cc/sphinx/ext/autosummary/__init__.py#L736

Will add a comment about that

[codecov]

Codecov Report

Merging #24232 into master will decrease coverage by 49.2%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           master   #24232       +/-   ##
===========================================
- Coverage   92.21%      43%   -49.21%     
===========================================
  Files         162      162               
  Lines       51763    51763               
===========================================
- Hits        47733    22261    -25472     
- Misses       4030    29502    +25472

Flag	Coverage Δ
#multiple	?
#single	43% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/io/formats/latex.py	0% <0%> (-100%)	⬇️
pandas/core/categorical.py	0% <0%> (-100%)	⬇️
pandas/io/sas/sas_constants.py	0% <0%> (-100%)	⬇️
pandas/tseries/plotting.py	0% <0%> (-100%)	⬇️
pandas/tseries/converter.py	0% <0%> (-100%)	⬇️
pandas/io/formats/html.py	0% <0%> (-98.62%)	⬇️
pandas/core/groupby/categorical.py	0% <0%> (-95.46%)	⬇️
pandas/io/sas/sas7bdat.py	0% <0%> (-91.17%)	⬇️
pandas/io/sas/sas_xport.py	0% <0%> (-90.15%)	⬇️
pandas/core/tools/numeric.py	10.44% <0%> (-89.56%)	⬇️
... and 119 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 f6c7f6b...61b6a82. Read the comment docs.

[codecov]

Codecov Report

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

@@            Coverage Diff             @@
##           master   #24232      +/-   ##
==========================================
+ Coverage   92.21%   92.21%   +<.01%     
==========================================
  Files         162      162              
  Lines       51763    51763              
==========================================
+ Hits        47733    47734       +1     
+ Misses       4030     4029       -1

Flag	Coverage Δ
#multiple	90.61% <ø> (ø)	⬆️
#single	43.01% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/util/testing.py	87.41% <0%> (-0.1%)	⬇️
pandas/io/json/json.py	93.09% <0%> (+0.47%)	⬆️

---

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 f6c7f6b...61b6a82. Read the comment docs.

[datapythonista]

thanks @jorisvandenbossche

we don't have autosummaries anywhere else, do we?