Contribution Number: 1
Student: Brittney Lilly
Issue: pytorch/ao#3863 (comment)
Status: Phase I Complete, Phase II In Progress
I chose this issue because it has an immediate and visible impact on the documentation that contributors and users of the TorchAO library rely on. I wanted to work on something where I could clearly trace the impact. This issue also matched my current skill level, as this is my first issue in the pytorch/ao repository, so I wanted to start with an issue that didn’t require robust knowledge of this codebase. I am currently familiar with HTML but I hope to learn how Sphinx builds documentation from plain text files.
The pytorch/ao repository (also known as TorchAO) uses Sphinx, a document generator, to read plain text markdown and reStructuredText (RST) files in TorchAO’s docs folder and convert them into publishable HTML documents that are hosted on the official TorchAO documentation website. The problem is that when Sphinx is trying to build the publishable documents, it encounters files with RST/Markdown formatting issues, missing or broken links and references, missing files, and/or import failures. When Sphinx encounters these issues, it produces a warning but continues to build and publish the file. The result is that published material displayed may be visually malformed, not visible to users, or contain missing or broken parts. The goal of this issue is to find and fix the files that generate these warnings. At the start of the issue on 6/17/2025, there are currently 4 warnings being generated.
[What should happen?]
[What actually happens?]
[Which parts of the codebase are involved?]
Setting up my local development environment was more involved than I expected. Because I am on a Windows computer, I had to use WSL2 (Windows Subsystem for Linux) with Ubuntu to run Linux commands like make html that don't work natively on Windows. I installed Miniconda inside Ubuntu to create an isolated virtual environment for the project, then installed the project dependencies by running the four install commands from the doc_build.yml workflow file. One challenge I ran into was that GitHub Desktop could not recognize my repository because it lives inside the WSL file system rather than directly on my Windows C drive, so I still need to resolve how to authenticate and push branches from Ubuntu to GitHub.
- Created and activated a conda virtual environment using Python 3.11 inside Ubuntu
- Installed the project dependencies by running the four install commands derived from the doc_build.yml workflow file
- Navigated into the docs folder and ran make html to trigger Sphinx to build the documentation and reproduce the warnings
- Repeated step 3 three times to ensure the warning were triggered consistently
- Observed 3 warnings in the build output, confirming the issue exists in the current state of the repository
-
Commit showing reproduction: [Link to commit in your fork]
-
Screenshots/logs: Screenshot showing 3 warnings produced
-
My findings: Observed 3 warnings in the build output, confirming the issue exists in the current state of the repository
[Your analysis of the root cause - what's causing the issue?]
[High-level description of your fix approach]
Using UMPIRE framework (adapted):
Understand: [Restate the problem]
Match: [What similar patterns/solutions exist in the codebase?]
Plan: [Step-by-step implementation plan]
- [Modify file X to do Y]
- [Add function Z]
- [Update tests]
Implement: [Link to your branch/commits as you work]
Review: [Self-review checklist - does it follow the project's contribution guidelines?]
Evaluate: [How will you verify it works?]
- Test case 1: [Description]
- Test case 2: [Description]
- Test case 3: [Description]
- Integration scenario 1
- Integration scenario 2
[What you tested manually and results]
[What you built this week, challenges faced, decisions made]
[Continue documenting as you work]
- Files modified: [List]
- Key commits: [Links to important commits]
- Approach decisions: [Why you chose certain approaches]
PR Link: [GitHub PR URL when submitted]
PR Description: [Draft or final PR description - much of the content above can be adapted]
Maintainer Feedback:
- [Date]: [Summary of feedback received]
- [Date]: [How you addressed it]
Status: [Awaiting review / Iterating / Approved / Merged]
[What you learned technically]
[What was hard and how you solved it]
[Reflection on your process]
- [Link to helpful documentation]
- [Tutorial or Stack Overflow post that helped]
- [GitHub issues or discussions that helped]