DOC: add back currentmodule to api.rst
State: closed

xref https://github.com/pandas-dev/pandas/pull/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.

Labels:
name: Docs

Comments:
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)
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.
Oh, sorry, I understood now, didn't get the problem with the links. Seems like a bug in sphinx then?
> 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.
> 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.
> 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? 
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
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](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=h1) Report
> Merging [#24232](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/f6c7f6be80c83ad9f4680fc7bcd5bf9e5b426d92?src=pr&el=desc) will **decrease** coverage by `49.2%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/24232/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=tree)

```diff
@@             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% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/formats/latex.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvbGF0ZXgucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/core/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY2F0ZWdvcmljYWwucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/sas/sas\_constants.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXNfY29uc3RhbnRzLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/plotting.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvcGxvdHRpbmcucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvY29udmVydGVyLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/formats/html.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvaHRtbC5weQ==) | `0% <0%> (-98.62%)` | :arrow_down: |
| [pandas/core/groupby/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9jYXRlZ29yaWNhbC5weQ==) | `0% <0%> (-95.46%)` | :arrow_down: |
| [pandas/io/sas/sas7bdat.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXM3YmRhdC5weQ==) | `0% <0%> (-91.17%)` | :arrow_down: |
| [pandas/io/sas/sas\_xport.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXNfeHBvcnQucHk=) | `0% <0%> (-90.15%)` | :arrow_down: |
| [pandas/core/tools/numeric.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvdG9vbHMvbnVtZXJpYy5weQ==) | `10.44% <0%> (-89.56%)` | :arrow_down: |
| ... and [119 more](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=footer). Last update [f6c7f6b...61b6a82](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=h1) Report
> Merging [#24232](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/f6c7f6be80c83ad9f4680fc7bcd5bf9e5b426d92?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/24232/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=tree)

```diff
@@            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% <ø> (ø)` | :arrow_up: |
| #single | `43.01% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `87.41% <0%> (-0.1%)` | :arrow_down: |
| [pandas/io/json/json.py](https://codecov.io/gh/pandas-dev/pandas/pull/24232/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2pzb24vanNvbi5weQ==) | `93.09% <0%> (+0.47%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=footer). Last update [f6c7f6b...61b6a82](https://codecov.io/gh/pandas-dev/pandas/pull/24232?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).