Documentation Issues

[kmaehashi]

Topics to be covered (User's Guide)

• [x] source link dead: https://docs.cupy.dev/en/stable/reference/generated/cupy.cuda.using_allocator.html (#6126)
• [x] some functions are undocumented (e.g. cupy.conjugate): https://docs.cupy.dev/en/stable/reference/comparison.html (fixed via #4945)

Topics to be covered (API Reference)

• [x] Add notes for cupy.cuda.profiler.initialize, saying that this feature is deprecated in CUDA Toolkit and may be removed in future versions

Broken docstring formats (easy to fix, contribution welcome!)

• [ ] https://docs.cupy.dev/en/latest/reference/generated/cupy.cuda.using_allocator.html
• [ ] https://docs.cupy.dev/en/latest/reference/generated/cupyx.distributed.init_process_group.html > Returns:
• [ ] https://docs.cupy.dev/en/stable/reference/generated/cupyx.scipy.ndimage.affine_transform.html > texture_memory
• [ ] https://docs.cupy.dev/en/latest/reference/generated/cupyx.scipy.special.erf.html#cupyx.scipy.special.erf > scipy.special.erf()

Outdated docstrings (easy to fix, contribution welcome!)

• [ ] cupy.asarray docstring says This function currently does not support the order option. but this is no longer valid and should be removed.

[leofang]

It'd be nice to also document cupyx.time.repeat and mention it in, say, the tutorial, for how to perform a fair timing.

[leofang]

related: #3692

[leofang]

I don't remember where we discussed this (sorry!), but we should also document common ROCm/HIP pitfalls.

[leofang]

@kmaehashi I'd like to have a new page added to "Tutorial", placed between "Basics of CuPy" and "User-Defined Kernels". I am thinking to call it "Advanced Tricks of Using CuPy", in which we cover (a) a number of topics that advanced users would appreciate and (b) a number of items in which we invested efforts and would like users to try and give us feedbacks. My current list is:

• [x] How to use streams and events (we can mention PTDS here)
• [x] How to measure GPU time correctly (Ans: use cupyx.time.repeat)
• [x] Advanced FFT usage (cuFFT plan as context manager, inspect/manipulate the plan cache, multi-GPU FFT, callbacks, etc)
• [x] Link to "Interoperability"
• [ ] Kernel autotuning with Optuna
• [x] CUB/cuTENSOR Backend (a demo using sum to show the speedup)
• [ ] ...what else? Comments and suggestions are welcome!

I'd also like to add a few more examples for RawModule (in "User-Defined Kernels"), mainly to show what can be done with the new options:

• [x] translate_cucomplex
• [x] name_expressions
• [x] jitify

I am hoping to get all these done in time before the code-freeze for v9.0.0, but we'll see....

[kmaehashi]

Thanks Leo! These docs would definitely help users 😄 I feel however these topics are more than "Tutorial" things. (that's why I reverted this: #4857) I'm thinking it's better to rename "Tutorial" to "User Guide" following NumPy's docs: https://numpy.org/devdocs/user/index.html Then we can move topics like Interoperability, Memory Management, API Compatibility Policy, Difference between CuPy and NumPy, License, etc. to there, instead of wildcard "API Reference" section.

Some other topics I would cover is #1566.

[leofang]

I'm thinking it's better to rename "Tutorial" to "User Guide" following NumPy's docs: https://numpy.org/devdocs/user/index.html Then we can move topics like Interoperability, Memory Management, API Compatibility Policy, Difference between CuPy and NumPy, License, etc. to there, instead of wildcard "API Reference" section.

Sounds good, @kmaehashi! If you send a restructuring PR for this I'll be able to build upon it. I can also send it if you like.

[leofang]

I can also send it if you like.

Ongoing in #5093. I don't think I have time to cover everything I wanted to add before the v9 code frozen, but it's a start...