-
Notifications
You must be signed in to change notification settings - Fork 467
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
base: master
Are you sure you want to change the base?
Conversation
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.
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
***@***.***
|
@@ -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.
@@ -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.
@@ -1,13 +1,9 @@ | |||
Torch Export to StableHLO | |||
-------------------------- | |||
# Torch Export to StableHLO |
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 in a separate feature dir, this is not a contribute doc.
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.
In fact only
[Bazel in Pytorch/XLA](https://github.com/pytorch/xla/pull/7988/files#)
[Codegen migration Guide](https://github.com/pytorch/xla/pull/7988/codegen_migration.html)
[OP Lowering Guide](https://github.com/pytorch/xla/pull/7988/op_lowering.html)
[Custom Hardware Plugins](https://github.com/pytorch/xla/pull/7988/plugins.html)
belong to Contribute to Pytorch/XLA
. Please move everything else in a feature dir.
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.