-
Notifications
You must be signed in to change notification settings - Fork 471
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Creates a new table of contents to organize content #7988
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, Mike. I started a CI run so I can look at the github pages docs preview.
I'm still not sure about converting everything to RST -- just about everyone knows markdown, but I don't know how much of the team actually knows RST. Even if it's easy to learn, I don't want that to be a barrier or source of friction. Can you give more details about the issue you were seeing with the TOC? There may be some sphinx setting we can tweak to make MD work. IIUC anything not in index.rst
would not show up as a TOC node.
CONTRIBUTING.md
Outdated
@@ -1,181 +0,0 @@ | |||
# Contribute To PyTorch/XLA |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO developer-oriented documentation (at least CONTRIBUTING
) should stay at the top level or in docs
, since contributors will probably look for instructions on our GitHub repository.
Moving API guide is a good idea, since that's user-facing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I moved the content to the docs/source directory because that is where Sphinx is looking for it. None of the docs outside of the source directory were being picked up by the doc build process. I'm OK with leaving CONTRIBUTING in the docs directory. I prefer to not have all docs in a single directory because that makes it difficult to find a file you want to update. We can add a comment in CONTRIBUTING about how we structure the docs to explain how to find a file.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I will look into using markdown. The docs use the Pytorch Sphinx theme, perhaps there is a TOC setting that would help.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was able to get markdown files to work. I've pushed the updates to the branch I used when I created the PR.
I couldn't find a way to respond to this comment on GitHub, so I'm sending
this email. I will look into putting the "getting started" content to the
landing page. By default the HTML that Sphinx builds for the landing page
is just a copy of the TOC. But I think we can add some additional content
before the TOC. I couldn't find a way to remove the TOC from the landing
page entirely. I'll do some digging,
…On Mon, Sep 16, 2024 at 1:40 PM Will Cromar ***@***.***> wrote:
The sidebar is looking better for sure:
image.png (view on web)
<https://github.com/user-attachments/assets/661c379e-980f-4a29-a70b-03a51bb2afe5>
Is it possible to keep some sort of "getting started" content on the
landing page, at least the pip install instructions and a basic example?
This is where I land after this PR:
image.png (view on web)
<https://github.com/user-attachments/assets/cf0134fb-3703-4402-91aa-f8b6a5bc53ee>
—
Reply to this email directly, view it on GitHub
<#7988 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AOG3RGRV63RTXG5IXESU27DZW4647AVCNFSM6AAAAABN7PNYNSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNJTHE4DQNRSGQ>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
--
[image: Google Logo]
Michael Green
Technical Writer
***@***.***
|
docs/source/perf/fix_aten_ops.md
Outdated
@@ -0,0 +1,71 @@ | |||
# Fix attention ops | |||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
where is this doc coming from? It felt like a prt of the export but does not have much context and is confusing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This content came from xla/docs/FIX_LOWERING_FOR_CORE_ATEN_OPS.md
Since it doesn't have much content or context, I will remove it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
you can just add it back to the FIX_LOWERING_FOR_CORE_ATEN_OPS
I guess
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The file has been renamed to fix_aten_ops.md. I can re-add it, but if it is confusing, without context, and without a specific purpose, I'd rather leave it out.
docs/source/contribute/amp.md
Outdated
@@ -0,0 +1,149 @@ | |||
# Automatic Mixed Precision |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this should be part of perf
, not contribute
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
or rather just have a separate features directory.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The directory names are loosely CUJ based and are following the convention we use in the cgc documentation. I think this doc would be fine in the perf directory, so I will move it there.
80f9847
to
e3cf356
Compare
I moved all content files into a directory under /docs/source so they will be picked up by the doc build process. I converted the markdown files to restructedText to clean up the TOC. I did this because all headers in a markdown file are added as a node in the TOC which results in a TOC that is way too long. I shortened some of the file names as well.