apache / apache/beam

Annotate code references inside inline documentation in Python-SDK

Open
#18,232 0 comments 0 reactions 0 assignees View on GitHub
core good first issue improvement P3 python
Dominant language
Java
Stars
8.7k
Forks
4.7k
Avg merge
1d 20h
Merged PRs (30d)
196

Description

Some of the inline documentation in Python-SDK contains references to classes, methods or fields. The document generation tool (Sphinx) supports annotating such code blocks.

If the inline documentation is annotated properly then the references will be linked (clickable) on the generated site.

Relevant Sphinx documentation:
http://www.sphinx-doc.org/en/stable/markup/inline.html#xref-syntax

Imported from Jira [BEAM-1756](https://issues.apache.org/jira/browse/BEAM-1756). Original Jira may contain additional context.
Reported by: tibor.kiss@gmail.com.

Contributor guide

Open the contributing guide

Research direction

Start by locating the Python-SDK inline documentation that references classes, methods, or fields, then review Sphinx's inline xref syntax documentation. Work through the relevant references and verify the generated site makes them clickable; the task is done when the applicable code references are annotated consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.