API Docs Rework #18147
Labels
Comments
|
I indeed think we at least want to have a way to only document certain methods/attributes on a class, to prevent including all. Something like outlined above (with the |
|
I think the above is somewhat the minimal we need to be able to document all classes, without an explosion of docstring pages. We could also try to limit the pages we currently already have (eg remove the duplicate pages for DatetimeIndex and TimedeltaIndex), but then we might need to provide redirects. |
|
So some other related issue to the API docs:
|
|
For moving to IPython.sphinxext, I think the only new warnings are which is good because those figures don't exist. They're in |
|
If we want to go completely warning free, we also have those ones in the beginning of the build: |
|
@jorisvandenbossche not sure if this will work for the cyfuncs, but see the second example here Perhaps if we put the function signature on the first line of the docstring, numpydoc / sphinx will not attempt to introspect the cyfunc? |
That might be an option (at least worth a try), but, that means we need to override all those inherited methods I think ? For the attributes listing, I commented here: numpy/numpydoc#106 (comment) |
|
Some progress: IPython fix is merged: ipython/ipython#10907, and I also opened a PR to sphinx (for the missing listing of attributes): sphinx-doc/sphinx#4247 |
|
FYI Sphinx the 1.7 beta is out https://pypi.org/project/Sphinx/1.7.0b1/ They've removed Checking the timing now. I think Joris noted that things weren't as slow as 1.6x? |
|
Good you notice. We should make sure this time to test sphinx before they release. |
This was referenced Feb 12, 2018
|
Some warnings / errors from a recent build with
With the vendored versions removed: |
|
I think that #19657 is fixing errors like |
|
I was also checking the recent travis logs, and a big part of the warnings are due to recent deprecations / removals (eg Panel started to warn more loudly). |
4 tasks
|
Things here seem to be mostly fixed. The only remaining one is things like Index.name |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
What do we want out of our API docs? What are the current issues?
I think we're (mostly) happy with
api.rst: we manually list the classes and methods that we want to include the docs, grouped by topics of our choosing.I think we're unhappy with some aspects of the auto-genrated class pages.
The hack in our vendored
numpydoc.py"fixing" the autosummary to not include a table of methods for certain classes. This avoids a ton of redundant pages with the parent class, but we can't call out important differences likeRangeIndex.startWe'd like a way to limit autosummary to specific methods in a class (I think this can be done with a
Methodssection in the docstring)Tasks:
cache_readonlycopying docstring (The use of @cache_readonly removes the docstring of attributes #18197)Index.nameand other class attributes. Either fix in numpydoc to use sphinx magic, or make into propertiesDataFrame.indexandDataFrame.columns(Allow accessing AxisProperties on classes #18196)The text was updated successfully, but these errors were encountered: