[
https://issues.apache.org/jira/browse/BEAM-12235?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17472925#comment-17472925
]
Beam JIRA Bot commented on BEAM-12235:
--------------------------------------
This issue is assigned but has not received an update in 30 days so it has been
labeled "stale-assigned". If you are still working on the issue, please give an
update and remove the label. If you are no longer working on the issue, please
unassign so someone else may work on it. In 7 days the issue will be
automatically unassigned.
> 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
> Assignee: David Huntsperger
> Priority: P2
> Labels: stale-assigned
>
> 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)
