Creates a new table of contents to organize content

[mikegre-google]

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.

[will-cromar]

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.

[will-cromar]

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.

[mikegre-google]

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.

[mikegre-google]

I will look into using markdown. The docs use the Pytorch Sphinx theme, perhaps there is a TOC setting that would help.

[mikegre-google]

I was able to get markdown files to work. I've pushed the updates to the branch I used when I created the PR.

[will-cromar]

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 pip install instructions and a basic example? This is where I land after this PR:

[mikegre-google]

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 ***@***.***

[JackCaoG]

where is this doc coming from? It felt like a prt of the export but does not have much context and is confusing.

[mikegre-google]

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.

[JackCaoG]

you can just add it back to the FIX_LOWERING_FOR_CORE_ATEN_OPS I guess

[mikegre-google]

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.

[JackCaoG]

this should be part of perf, not contribute

[JackCaoG]

or rather just have a separate features directory.

[mikegre-google]

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.

[JackCaoG]

this should be in a separate feature dir, this is not a contribute doc.

[JackCaoG]

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.

[mikegre-google]

A directory named "feature" doesn't fit with the rest of the directory names. They each indicate some sort of action the reader is taking: learning about PT/XLA, contributing to PT/XLA, etc. The topics currently under "contribute" are only useful for those customers that will be contributing to the PT/XLA project, so I think it makes sense to put them there. @will-cromar had suggested I place them there as well. Please explain why you feel these topics don't belong in "contribute".

[JackCaoG]

IMO contribute are a set of docs for the contributor, it can includes things like how to setup developer env, how to contribute a codegen/op lowering.

Export on the other hand is a feature that we want user to use. It is used to exporting a model to a stableHLO. Contributor does not need to know how export works, but we want user to see this doc and aware this feature exists. sample arguments applied to other docs. Some of the features are for the perfomrances, some features don't but they are still user facing doc, not contributor facing.