[Doc] Restructure core API docs #32236
Conversation
Signed-off-by: Jiajun Yao <jeromeyjj@gmail.com>
This reverts commit 7aa8d6f.
| {% if methods %} | ||
| .. rubric:: {{ _('Methods') }} | ||
|
|
||
| .. autosummary:: |
There was a problem hiding this comment.
This will generate stub page for each class method and attribute which will make the doc build even longer but that's what other libraries (e.g. pandas, numpy) are doing.
There was a problem hiding this comment.
@jjyao is there a compromise we could find here? this seems to more than double the build time now. I'm in touch with support from readthedocs.org right now to make longer builds happen, but for now we can't pull this off.
just asking if we can think of a trade-off and move towards a more extensive solution later?
There was a problem hiding this comment.
we can try to not autosummary class members
There was a problem hiding this comment.
yep, let's try this for now and see how it impacts build times. this PR increases rtd builds from 900s to 2000+, which will always time out
There was a problem hiding this comment.
Seems that doesn't work: https://buildkite.com/ray-project/oss-ci-build-pr/builds/11774#01863776-7701-40d6-974c-b6fe51e9d705 since we have places that manually autosummary class members which creates duplications with autoclass.
There was a problem hiding this comment.
ok, so be it. we just have to make sure we stay below 3000s total, once all other libs merge their changes. might be risky.
doc/source/ray-references/api.rst
Outdated
| @@ -13,4 +13,4 @@ API References | |||
| ../rllib/package_ref/index.rst | |||
| ../workflows/package-ref.rst | |||
| ../cluster/package-overview.rst | |||
| ../ray-core/package-ref.rst | |||
| ../ray-core/reference/index.rst | |||
There was a problem hiding this comment.
Checked several libraries (pandas, spark, numpy, scipy), seems there api docs have the following structure:
reference/
index.rst
group1.rst
group2.rst
api|generated/class1.rst
api|generated/class1.rst
I feel it's better than
api/
api.rst
group1.rst
group2.rst
doc/class1.rst
doc/class1.rst
so I tried it out in this PR. Would like to get other's opinions on this.
There was a problem hiding this comment.
note that every folder structure change impacts backward compatibility. the URLs will change, so I think we should keep the current structure (i.e. api, not reference, but we can of course rename to index etc.)
This is a known issue with autosummary: sphinx-doc/sphinx#9884. @maxpumperla can we ignore it for now? |
jjyao
requested review from
edoakes,
simon-mo,
jiaodong,
shrekris-anyscale,
sihanwang41,
architkulkarni,
wuisawesome,
DmitriGekhtman and
pcmoritz
as code owners
|
@jjyao Looks like this PR broke the doctests job: |
|
Yup, I'm aware of that and I have a follow-up PR to fix it. Please don't revert this :) |
jjyao
removed
the
@author-action-required
Similar to #31204, refactor the core api reference for better layout and view. Signed-off-by: Jiajun Yao <jeromeyjj@gmail.com>
Similar to ray-project#31204, refactor the core api reference for better layout and view. Signed-off-by: Jiajun Yao <jeromeyjj@gmail.com> Signed-off-by: Edward Oakes <ed.nmi.oakes@gmail.com>
Similar to ray-project#31204, refactor the core api reference for better layout and view. Signed-off-by: Jiajun Yao <jeromeyjj@gmail.com> Signed-off-by: elliottower <elliot@elliottower.com>
Signed-off-by: Jiajun Yao jeromeyjj@gmail.com
Why are these changes needed?
Similar to #31204, refactor the core api reference for better layout and view.
Related issue number
Closes #32079
Checks
git commit -s) in this PR.scripts/format.shto lint the changes in this PR.