Fix API documentation generation #3029
Conversation
melissawm
requested review from
A9isha,
Lumosis,
NicoGrande,
NuojCheng,
RissyRan,
SurbhiJainUSC,
aireenmei,
bvandermoon,
gagika,
gobbleturk,
gpolovets1,
hengtaoguo,
jacoguzo,
jesselu-google,
jiangjy1982,
jrplatin,
khatwanimohit,
mailvijayasingh,
michelle-yooh,
mitalisi,
parambole,
patemotter,
richjames0,
shralex,
shuningjin,
suexu1025,
vipannalla and
xuefgu
as code owners
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
|
mdformat should not be running on all files here, as far as I understand. I'll investigate and solve the remaining CI checks. |
melissawm
force-pushed
the
fix-api-docs
branch
from
5f36ea3 to
5685fb9
Compare
melissawm
force-pushed
the
fix-api-docs
branch
from
5685fb9 to
7562b4a
Compare
|
|
||
| # 3. Install MaxText and its dependencies | ||
| uv pip install maxtext --resolution=lowest | ||
| install_maxtext_github_deps |
There was a problem hiding this comment.
I think this has been removed unintentionally?
There was a problem hiding this comment.
Actually this was removed intentionally - I can't find this file in the codebase, and it is not necessary for installation, so I figured the installation instructions were outdated (as noted in my first comment)
Can you confirm what the correct instructions are? Thanks!
There was a problem hiding this comment.
I think that this line should stay. I dont know which file it points to but I believe its necessary for dependency installation,
There was a problem hiding this comment.
The content in this doc does need a refresh though. Lets work on it on a different PR :))
jacoguzo
left a comment
jacoguzo
left a comment
There was a problem hiding this comment.
Added some comments, ideally someone from ENG should review too.
|
|
||
| # for import docs | ||
| -r base_requirements/requirements.txt | ||
| google-tunix |
There was a problem hiding this comment.
What is the effect of removing these dependencies?
| "google_cloud_mldiagnostics", | ||
| "jetstream", | ||
| "librosa", | ||
| "ml_goodput_measurement", |
There was a problem hiding this comment.
Why are these libraries being imported to the docs? What is the effect of removing them?
|
|
||
| # 3. Install MaxText and its dependencies | ||
| uv pip install maxtext --resolution=lowest | ||
| install_maxtext_github_deps |
There was a problem hiding this comment.
I think that this line should stay. I dont know which file it points to but I believe its necessary for dependency installation,
|
|
||
| # 3. Install MaxText and its dependencies | ||
| uv pip install maxtext --resolution=lowest | ||
| install_maxtext_github_deps |
There was a problem hiding this comment.
The content in this doc does need a refresh though. Lets work on it on a different PR :))
| from MaxText import pyconfig | ||
| from MaxText.globals import MAXTEXT_PKG_DIR, MAXTEXT_ASSETS_ROOT | ||
| from maxtext.inference_microbenchmark import run_benchmarks | ||
| from maxtext.inference.inference_microbenchmark import run_benchmarks |
There was a problem hiding this comment.
Does this change of "inference_microbenchmark" location impact our current recipes/ dependency installation for RL tutorials?
3 participants
Description
This PR fixes the RTD documentation generation and deployment by eliminating many formatting issues, some importing errors and warnings resulting from the docstring generation via apidoc.
The main issue I fixed was to remove many of the docs dependencies, since they can be mocked in the
conf.pyfile and that makes the docs generation process faster and lighter. I also fixed a couple of typos, and reviewed the installation instructions which looked to me to be outdated (please confirm).This is a big PR since it involves many files, but changes are all in docstrings, so should not have any effect on actual code. In addition to fixing warnings, I also went ahead and reviewed as many docstrings as I could to fix formatting, make them consistent and better looking for the generated documentation website. Docstrings are written in rst format, and some of them were written in a markdown flavor - this is something to be aware of in the future (see https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
Tests
Documentation builds correctly (and quickly) locally.
Checklist
Before submitting this PR, please make sure (put X in square brackets):
gemini-reviewlabel.