Where to expose arcade.camera API?

[cdeil]

Currently the links from the tutorial and programming guide to the camera API docs are broken.

https://api.arcade.academy/en/latest/tutorials/platform_tutorial/step_07.html

https://api.arcade.academy/en/latest/programming_guide/camera.html#key-objects

The reason is that currently the place of exposure in the API docs is arcade.Camera2D at the top level arcade namespace:

https://api.arcade.academy/en/latest/api_docs/api/camera_2d.html#arcade.Camera2D

and other classes & functions are exposed in deeply nested submodules like arcade.camera.orthographic.OrthographicProjector:

https://api.arcade.academy/en/latest/api_docs/api/advanced_cameras.html#arcade.camera.orthographic.OrthographicProjector

For example here you mention in a changelog to users that objects would be exposed at arcade.camera.Camera2D or arcade.camera.OrthographicProjector:

https://github.com/pythonarcade/arcade/blob/development/CHANGELOG.md#camera

Actually all those classes are exposed in the arcade.camera namespace already, it's only the docs which are confusing / links broken.

Do you want to keep arcade.Camera2D or remove it here and only expose it as arcade.camera.Camera2D?

arcade/arcade/__init__.py

Line 225 in f4f4521

from .camera import Camera2D

For all the others I see somehow you generate doc/api_docs/api/advanced_cameras.rst with entries like this:

.. autoclass:: arcade.camera.data_types.OrthographicProjectionData
   :members:

.. autoclass:: arcade.camera.orthographic.OrthographicProjector
   :members:

Would it be OK to change and expose those API docs in the arcade.camera namespace?
I would be +1 on this since deeply nested imports are harder to explore and remember.

Related: #2239

[einarf]

Arcade used to be very flat with everything available in the root namespace. As the library now offers more advanced options we expose the basic members used by 99% of users in the root and leave the more advanced members in the sub-module.

Currently we want arcade.Camera2D because of compatibility and simplicity. This might change in the future but it's just how it has always been done.

There reason for the broken links are many. I've now fixed the ast resolved that figures out the shortest path to members in arcade and updates many rst files with broken and wrong links. The camera one should be flawless now. Also updated all usages in tutorials and examples.

#2613