added files converted back to md

docs/CONTRIBUTING.md

@@ -0,0 +1,218 @@
+# Contribute To PyTorch/XLA
+
+We appreciate all contributions. If you are planning to contribute a bug
+fix for an open issue, please comment on the thread and we're happy to
+provide any guidance. You are very welcome to pick issues from [good first issue](https://github.com/pytorch/xla/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+and [help wanted](https://github.com/pytorch/xla/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
+labels.
+
+If you plan to contribute new features, utility functions or extensions
+to the core, please first open an issue and discuss the feature with us.
+Sending a PR without discussion might end up resulting in a rejected PR,
+because we might be taking the core in a different direction than you
+might be aware of.
+
+## Building from source
+
+We recommend you to use our prebuilt Docker image to start your
+development work using one of the two following methods.
+
+### Visual Studio Code Dev Container
+
+-   Create an empty directory (optionally on a remote host via SSH) and
+    open it in VSCode. Then, clone PyTorch, TorchVision, and
+    PyTorch/XLA:
+
+    ``` console
+    git clone --recursive --depth=1 https://github.com/pytorch/pytorch.git
+    # Optional: install TorchVision if you need to run tests that involve vision modules
+    git clone --recursive --depth=1 https://github.com/pytorch/vision.git
+    git clone https://github.com/pytorch/xla.git pytorch/xla
+    # Optional: use [email protected]:pytorch/xla.git instead if you prefer to use SSH with key forwarding
+    ```
+
+-   Link (or copy) VSCode configuration to your workspace directory:
+
+    ``` console
+    ln -s pytorch/xla/.devcontainer/ .devcontainer
+    ln -s pytorch/xla/contrib/vscode/ .vscode
+    ln -s pytorch/xla/.style.yapf .style.yapf
+    ln -s pytorch/xla/.clang-format .clang-format
+    ```
+
+-   From VSCode's command menu, run `Reopen in Container` from the
+    command palette (F1 key) to open your workspace in one of our
+    pre-built Docker containers. Select the correct container config
+    based on your local accelerator (default to `tpu-contributor` if you
+    are not sure).
+
+    -   If you cannot find `Reopen in Container`, make sure the
+        `Dev Containers` VSCode extension is installed, then open the
+        `pytorch/xla` folder in VSCode.
+
+-   Since you are running as root in this container, teach `git` to
+    recognize the repositories you just cloned (outside of docker) as
+    safe:
+
+    ``` console
+    git config --global --add safe.directory /workspaces/torch/pytorch
+    git config --global --add safe.directory /workspaces/torch/pytorch/xla
+    git config --global --add safe.directory /workspaces/torch/vision
+    ```
+
+-   Build PyTorch, TorchVision, and PyTorch/XLA:
+
+    ``` console
+    cd pytorch
+    # pytorch/xla requires pytorch wheel to be presented under pytorch/dist
+    python setup.py bdist_wheel
+    python setup.py install
+    cd ..
+    cd vision
+    python setup.py develop
+    cd ..
+    cd pytorch/xla
+    python setup.py develop
+    # Optional: if you're using TPU, install libtpu
+    pip install torch_xla[tpu] -f https://storage.googleapis.com/libtpu-releases/index.html
+    ```
+
+-   Test your build
+
+    ``` console
+    python -c 'import torch_xla as xla; print(xla.device())'
+    # Output: xla:0
+    ```
+
+### Manually build in Docker container
+
+-   Setup Development Docker Image
+
+    ``` console
+    docker pull us-central1-docker.pkg.dev/tpu-pytorch-releases/docker/development:tpu
+    docker run --privileged --name ptxla -it -d -e "TERM=xterm-256color" us-central1-docker.pkg.dev/tpu-pytorch-releases/docker/development:tpu
+    docker exec --privileged -it ptxla /bin/bash
+    ```
+
+    All of the code below will be assumed to be run within the docker.
+
+-   Clone the PyTorch repo as per
+    [instructions](<https://github.com/pytorch/pytorch#from-source>).
+
+    ``` console
+    git clone --recursive https://github.com/pytorch/pytorch
+    cd pytorch/
+    ```
+
+-   Clone the PyTorch/XLA repo:
+
+    ``` console
+    git clone --recursive https://github.com/pytorch/xla.git
+    ```
+
+-   Build PyTorch
+
+    ``` console
+    # pytorch/xla requires pytorch wheel to be presented under pytorch/dist
+    python setup.py bdist_wheel
+    python setup.py develop
+    ```
+
+-   Build PyTorch/XLA
+
+    ``` console
+    cd xla/
+    python setup.py develop
+    ```
+
+### Additional steps for GPU
+
+Please refer to this
+[guide](<https://github.com/pytorch/xla/blob/master/docs/gpu.md#develop-pytorchxla-on-a-gpu-instance-build-pytorchxla-from-source-with-gpu-support>).
+
+## Before Submitting A Pull Request:
+
+In `pytorch/xla` repo we enforce coding style for both C++ and Python
+files. Please try to format your code before submitting a pull request.
+
+### C++ Style Guide
+
+`pytorch/xla` uses `clang-format-11` with a customized style config. If
+your PR touches the C++ source files, please run the following command
+before submitting a PR.
+
+``` console
+# How to install: sudo apt install clang-format-11
+# If your PR only changes foo.cpp, run the following in xla/ folder
+clang-format-11 -i -style=file /PATH/TO/foo.cpp
+# To format all cpp files, run the following in xla/ folder
+find -name '*.cpp' -o -name '*.h' -o -name '*.cc' | xargs clang-format-11 -i -style=file
+```
+
+### Python Style Guide
+
+`pytorch/xla` uses `yapf`(specially version 0.30.0 in case it's not
+backward compatible) with a customized style config. If your PR touches
+the Python source files, please run the following command before
+submitting a PR.
+
+``` console
+# How to install: pip install yapf==0.30.0
+yapf --recursive -i *.py test/ scripts/ torch_xla/ benchmarks/
+```
+
+### Running the Tests
+
+To run the tests, follow _one_ of the options below:
+
+-   Run on local CPU:
+
+    ``` console
+    export PJRT_DEVICE=CPU
+    ```
+
+-   Run on Cloud TPU:
+
+    ``` console
+    export PJRT_DEVICE=TPU
+    ```
+
+-   Run on GPU:
+
+    ``` console
+    export PJRT_DEVICE=CUDA GPU_NUM_DEVICES=${NUM_GPU}
+    ```
+
+For more detail on configuring the runtime, please refer to [this
+doc](<https://github.com/pytorch/xla/blob/master/docs/pjrt.md#quickstart>)
+
+If you are planning to be building from source and hence using the
+latest PyTorch/XLA code base, it is suggested for you to select the
+_nightly_ builds when you create a Cloud TPU instance.
+
+Then run `test/run_tests.sh` and `test/cpp/run_tests.sh` to verify the
+setup is working.
+
+### Useful materials
+
+1.  [OP Lowering
+    Guide](<https://github.com/pytorch/xla/blob/master/OP_LOWERING_GUIDE.md>)
+2.  [CODEGEN MIGRATION
+    GUIDE](<https://github.com/pytorch/xla/blob/master/CODEGEN_MIGRATION_GUIDE.md>)
+3.  [Dynamo Integration
+    Guide](<https://github.com/pytorch/xla/blob/master/docs/dynamo.md>)
+
+### Sharp Edges
+
+-   If local changes aren't visible, uninstall existing pytorch/xla
+    with `pip uninstall torch_xla` and `pip uninstall torch`, then
+    rebuild PyTorch and PyTorch/XLA with `python setup.py develop` or
+    `python setup.py install`.
+-   PJRT errors when running on TPU such as
+    `The PJRT plugin has PJRT API version 0.34. The framework PJRT API version is 0.40`.
+    You need to update your `libtpu.so` and ensure it's in your
+    `LD_LIBRARY_PATH` environmental directory. You can download a new
+    `libtpu.so` at [Google
+    Cloud](<https://storage.googleapis.com/libtpu-releases/index.html>),
+    which are sorted by date. Download the newest one and install it at
+    `pip install libtpu...whl`.

docs/README.md

@@ -0,0 +1,31 @@
+## Publish documentation for a new release.
+
+CI job `pytorch_xla_linux_debian11_and_push_doc` is specified to run on `release/*` branches, but it was not
+run on release branches due to "Only build pull requests" setting. Turning off "Only build pull requests" will result
+in much larger volumes in jobs which is often unnecessary. We're waiting for [this feature request](https://ideas.circleci.com/ideas/CCI-I-215)
+to be implemented so that we could override this setting on some branches.
+
+Before the feature is available on CircleCi side, we'll use a manual process to publish documentation for release.
+[Documentation for master branch](http://pytorch.org/xla/master/) is still updated automatically by the CI job.
+But we'll need to manually commit the new versioned doc and point http://pytorch.org/xla to the documentation of new
+stable release.
+
+Take 2.3 release as example:
+```
+# Build pytorch/pytorch:release/2.3 and pytorch/xla:release/2.3 respectively.
+# In pytorch/xla/docs
+./docs_build.sh
+git clone -b gh-pages https://github.com/pytorch/xla.git /tmp/xla
+cp -r build/* /tmp/xla/release/2.3
+cd /tmp/xla
+# Update `redirect_url` in index.md
+git add .
+git commit -m "Publish 2.3 documentation."
+git push origin gh-pages
+```
+## Adding new docs
+
+To add a new doc please create a `.md` file under this directory. To make this doc show up in our [doc pages](https://pytorch.org/xla/master/index.html), please add a `.rst` file under `source/`.
+
+## Adding images in the doc
+Please add your imges to both `_static/img/` and `source/_static/img/` for images to properlly show up in the markdown files as well as our [doc pages](https://pytorch.org/xla/master/index.html).

docs/source/accelerators/gpu.md

@@ -0,0 +1,6 @@
+# Learn about GPUs
+
+For information on GPUs on Google Cloud, see:
+
+-   [About GPUs on Google Cloud](https://cloud.google.com/compute/docs/gpus/overview)
+-   [GPU machine types](https://cloud.google.com/compute/docs/gpus)

docs/source/accelerators/tpu.md

@@ -0,0 +1,24 @@
+# Learn about TPUs
+
+Google Cloud TPUs are custom-designed AI accelerators, which are
+optimized for training and inference of large AI models. They are ideal
+for a variety of use cases, such as chatbots, code generation, media
+content generation, synthetic speech, vision services, recommendation
+engines, personalization models, among others.
+
+Cloud TPUs are designed to scale cost-efficiently for a wide range of AI
+workloads, spanning training, fine-tuning, and inference. Cloud TPUs
+provide the versatility to accelerate workloads on leading AI
+frameworks, including PyTorch, JAX, and TensorFlow. Seamlessly
+orchestrate large-scale AI workloads through Cloud TPU integration in
+Google Kubernetes Engine (GKE). Leverage Dynamic Workload Scheduler to
+improve the scalability of workloads by scheduling all accelerators
+needed simultaneously. Customers looking for the simplest way to develop
+AI models can also leverage Cloud TPUs in Vertex AI, a fully-managed AI
+platform.
+
+For more information, see:
+
+-   [Introduction to Cloud TPUs](https://cloud.google.com/tpu/docs/intro-to-tpu)
+-   [Set up a Cloud TPU environment](https://cloud.google.com/tpu/docs/setup-gcp-account)
+-   [Manage Cloud TPU resources](https://cloud.google.com/tpu/docs/managing-tpus-tpu-vm)