[
https://issues.apache.org/jira/browse/BEAM-12235?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17474857#comment-17474857
]
Beam JIRA Bot commented on BEAM-12235:
--------------------------------------
This issue is P2 but has been unassigned without any comment for 60 days so it
has been labeled "stale-P2". If this issue is still affecting you, we care!
Please comment and remove the label. Otherwise, in 14 days the issue will be
moved to P3.
Please see https://beam.apache.org/contribute/jira-priorities/ for a detailed
explanation of what these priorities mean.
> Python API reference docs need better organization
> ---------------------------------------------------
>
> Key: BEAM-12235
> URL: https://issues.apache.org/jira/browse/BEAM-12235
> Project: Beam
> Issue Type: Improvement
> Components: website
> Reporter: Stephan Hoyer
> Priority: P2
> Labels: stale-P2
>
> The first page of the reference API docs is helpful:
> https://beam.apache.org/releases/pydoc/2.28.0/index.html
> But diving in, I see the raw internal structure of Beam's Python modules,
> e.g.,
> https://beam.apache.org/releases/pydoc/2.28.0/apache_beam.io.html
> This is not very usable:
> - It's hard to navigate. I need to know exactly where a function is defined
> to find it. E.g., to find beam.Map, I had to click on
> "apache_beam.transforms package" followed by "apache_beam.transforms.core
> module" and then scroll down or search in the page for "Map."
> - It isn't clear exactly which components are public APIs. The documentation
> for few modules notes that they are not public, but there are so many others
> listed that I'm sure they cannot all be intended for public support. This
> makes it hard to find Beam's main public APIs.
> - It isn't clear the preferred import paths to use. For example,
> apache_beam.Map is documented as apache_beam.transforms.core.Map, without
> mention of the shorter name.
> I suspect the source of most of these issues is that the API docs make heavy
> use of Sphinx's autodoc for modules. In my experience maintaining Python
> projects, this just doesn't work very. autosummary and autofunction on
> individual functions/classes work well, but it needs to be organized by hand
> -- you can't count on automodule to do a good job of high level organization.
> JAX's docs are a good example, e.g., see
> https://github.com/google/jax/blob/master/docs/jax.rst and
> https://jax.readthedocs.io/en/latest/jax.html
> Happy to advise offline as well -- feel free to ping me at [email protected]
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
