Skip to content

DOC: fix API docs generation with sphinx 1.6 #16705

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Closed
jorisvandenbossche opened this issue Jun 15, 2017 · 4 comments · Fixed by #19687
Closed

DOC: fix API docs generation with sphinx 1.6 #16705

jorisvandenbossche opened this issue Jun 15, 2017 · 4 comments · Fixed by #19687
Labels
Milestone

Comments

@jorisvandenbossche
Copy link
Member

See discussion #16702 (comment). Pinned sphinx to 1.5* for now (#16704)

@jorisvandenbossche
Copy link
Member Author

@TomAugspurger this doesn't need to be fixed for 0.20.3 I think, but just have to remember to build the docs with 1.5* then, therefore tagging it for now as 0.20.3.

@jreback jreback modified the milestones: 0.20.3, 0.21.0 Jul 6, 2017
@jreback jreback modified the milestones: 0.21.0, Next Major Release Sep 23, 2017
@jorisvandenbossche jorisvandenbossche mentioned this issue Nov 9, 2017
15 tasks
@jorisvandenbossche
Copy link
Member Author

jorisvandenbossche commented Nov 10, 2017

Running the api docs locally with latest sphinx 1.6.5. Some observations:

  • reading the api generated pages is fast
  • We get a bunch of "WARNING: toctree references unknown document 'generated/pandas.DataFrame.blocks'" warnings, but not for every attribute/method. But I do not yet see a clear pattern (eg for DataFrame it warns for blocks, columns, empty', index, is_copy, ix, style)
  • it seems it is the writing of the pages that is really slow (as @TomAugspurger already noted somewhere before). In the progress output you can clearly see that each generated docstring page takes a noticeble 0.5 à 1.5 seconds to write (and since we have many of those pages ...)

@jorisvandenbossche
Copy link
Member Author

Regarding the extra warnings: the methods/attributes for which we get a new warning all seem to be methods/attributes that are not listed somewhere in the api.rst page.
So it seems that for some reason the 'hack' in the class template to include a commented autosummary toctree to include all methods/attributes there is no longer working or not including those specific methods/attributes.

For the slowdown I opened an issue on sphinx: sphinx-doc/sphinx#4230

@jorisvandenbossche
Copy link
Member Author

Again about the warnings, I was a bit too quick: after reading there is indeed only a limited number of warnings (as explained above), but after writing many warnings for all methods/attributes like ":: WARNING: toctree contains reference to nonexisting document 'generated/pandas.Timestamp.week' "

# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants