Creates a new table of contents to organize content #7988
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.
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.
| @@ -1,181 +0,0 @@ | |||
| # Contribute To PyTorch/XLA | |||
There was a problem hiding this comment.
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.
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.
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.
I was able to get markdown files to work. I've pushed the updates to the branch I used when I created the PR.
|
The sidebar is looking better for sure: Is it possible to keep some sort of "getting started" content on the landing page, at least the
|
|
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
***@***.***
|
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.