Skip to content

Commit

Permalink
Fix building docs instructions (pytorch#64508)
Browse files Browse the repository at this point in the history
Summary:
Fixes #{64507}

Removed duplicate instruction and linted the file a bit (consistent spacing around codeblocks/headers, adding code types in codeblocks, remove `$` from bash code blocks when uncecessary).

Pull Request resolved: pytorch#64508

Reviewed By: raghuramank100

Differential Revision: D30791164

Pulled By: mrshenli

fbshipit-source-id: a00db32dcfdd1ecc194c836f31174c806062eb6d
  • Loading branch information
Stevenjin8 authored and facebook-github-bot committed Sep 8, 2021
1 parent 4e98304 commit 71ba76b
Showing 1 changed file with 21 additions and 15 deletions.
36 changes: 21 additions & 15 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,6 @@ installed`. (You should only have to `pip uninstall` a few times, but
you can always `uninstall` with `timeout` or in a loop if you're feeling
lazy.)


```bash
conda uninstall pytorch -y
yes | pip uninstall torch
Expand All @@ -108,10 +107,8 @@ git submodule update --init --recursive --jobs 0

If you want to have no-op incremental rebuilds (which are fast), see the section below titled "Make no-op build fast."


3. Install PyTorch in `develop` mode:


The change you have to make is to replace

```bash
Expand Down Expand Up @@ -147,6 +144,7 @@ torch as it is not installed`; next run `python setup.py clean`. After
that, you can install in `develop` mode again.

### Tips and Debugging

* A prerequisite to installing PyTorch is CMake. We recommend installing it with [Homebrew](https://brew.sh/)
with `brew install cmake` if you are developing on MacOS or Linux system.
* Our `setup.py` requires Python >= 3.6
Expand Down Expand Up @@ -188,7 +186,7 @@ with `brew install cmake` if you are developing on MacOS or Linux system.
```
this is likely that you are using HTTP proxying and the certificate expired. To check if the certificate is valid, run
`git config --global --list` and search for config like `http.proxysslcert=<cert_file>`. Then check certificate valid date by running
```
```bash
openssl x509 -noout -in <cert_file> -dates
```
Expand Down Expand Up @@ -354,6 +352,7 @@ an optional dependency, and `pytest` may help run tests more selectively.
All these packages can be installed with `conda` or `pip`.

### Better local unit tests with `pytest`

We don't officially support `pytest`, but it works well with our
`unittest` tests and offers a number of useful features for local
developing. Install it via `pip install pytest`.
Expand All @@ -369,7 +368,6 @@ The above is an example of testing a change to all Loss functions: this
command runs tests such as `TestNN.test_BCELoss` and
`TestNN.test_MSELoss` and can be useful to save keystrokes.


### Local linting

You can run the same linting steps that are used in CI locally via `make`:
Expand Down Expand Up @@ -407,6 +405,7 @@ make clang-tidy
```

To run a lint only on changes, add the `CHANGED_ONLY` option:

```bash
make <name of lint> CHANGED_ONLY=--changed-only
```
Expand Down Expand Up @@ -501,14 +500,13 @@ pip install -r requirements.txt

> Note that if you are a Facebook employee using a devserver, yarn may be more convenient to install katex:
```
```bash
yarn global add katex
```

3. Generate the documentation HTML files. The generated files will be in `docs/build/html`.

```bash
cd docs
make html
```

Expand All @@ -533,6 +531,7 @@ git add index.rst jit.rst
```

#### Building C++ Documentation

For C++ documentation (https://pytorch.org/cppdocs), we use
[Doxygen](http://www.doxygen.nl/) and then convert it to
[Sphinx](http://www.sphinx-doc.org/) via
Expand Down Expand Up @@ -571,12 +570,13 @@ Then navigate to `localhost:8000` in your web browser.
**Tip:**
You can start a lightweight HTTP server on the remote machine with:

```
```bash
python -m http.server 8000 <path_to_html_output>
```

Alternatively, you can run `rsync` on your local machine to copy the files from
your remote machine:

```bash
mkdir -p build cpp/build
rsync -az me@my_machine:/path/to/pytorch/docs/build/html build
Expand Down Expand Up @@ -614,7 +614,7 @@ that has the ability to profile native code and Python code in the same session.
`py-spy` can be installed via `pip`:

```bash
$ pip install py-spy
pip install py-spy
```

To use `py-spy`, first write a Python test script that exercises the
Expand All @@ -637,7 +637,7 @@ number of times to get good statistics. The most straightforward way to use
graph](http://www.brendangregg.com/flamegraphs.html):

```bash
$ py-spy record -o profile.svg --native -- python test_tensor_tensor_add.py
py-spy record -o profile.svg --native -- python test_tensor_tensor_add.py
```

This will output a file named `profile.svg` containing a flame graph you can
Expand Down Expand Up @@ -706,6 +706,7 @@ variables `DEBUG`, `USE_DISTRIBUTED`, `USE_MKLDNN`, `USE_CUDA`, `BUILD_TEST`, `U
- `USE_XNNPACK=0` will disable compiling with XNNPACK.

For example:

```bash
DEBUG=1 USE_DISTRIBUTED=0 USE_MKLDNN=0 USE_CUDA=0 BUILD_TEST=0 USE_FBGEMM=0 USE_NNPACK=0 USE_QNNPACK=0 USE_XNNPACK=0 python setup.py develop
```
Expand Down Expand Up @@ -741,6 +742,7 @@ situations where files get rebuilt when a previous compilation was exactly the
same. Using ccache in a situation like this is a real time-saver.

Before building pytorch, install ccache from your package manager of choice:

```bash
conda install ccache -f conda-forge
sudo apt install ccache
Expand All @@ -764,12 +766,14 @@ build should be substantially and noticeably faster than the first build. If
this doesn't seem to be the case, check the `CMAKE_<LANG>_COMPILER_LAUNCHER`
rules in `build/CMakeCache.txt`, where `<LANG>` is `C`, `CXX` and `CUDA`.
Each of these 3 variables should contain ccache, e.g.

```
//CXX compiler launcher
CMAKE_CXX_COMPILER_LAUNCHER:STRING=/usr/bin/ccache
```

If not, you can define these variables on the command line before invoking `setup.py`.

```bash
export CMAKE_C_COMPILER_LAUNCHER=ccache
export CMAKE_CXX_COMPILER_LAUNCHER=ccache
Expand All @@ -778,6 +782,7 @@ python setup.py develop
```

#### Use a faster linker

If you are editing a single file and rebuilding in a tight loop, the time spent
linking will dominate. The system linker available in most Linux distributions
(GNU `ld`) is quite slow. Use a faster linker, like [lld](https://lld.llvm.org/).
Expand All @@ -786,7 +791,8 @@ People on Mac, follow [this guide](https://stackoverflow.com/questions/42730345/

The easiest way to use `lld` this is download the
[latest LLVM binaries](http://releases.llvm.org/download.html#8.0.0) and run:
```

```bash
ln -s /path/to/downloaded/ld.lld /usr/local/bin/ld
```

Expand Down Expand Up @@ -862,7 +868,7 @@ tensor([1., 2., 3., 4.], dtype=torch.float64)
GDB tries to automatically load `pytorch-gdb` thanks to the
[.gdbinit](.gdbinit) at the root of the pytorch repo. However, auto-loadings is disabled by default, because of security reasons:

```
```bash
$ gdb
warning: File "/path/to/pytorch/.gdbinit" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load".
To enable execution of this file add
Expand All @@ -880,11 +886,11 @@ For more information about this security protection see the
As gdb itself suggests, the best way to enable auto-loading of `pytorch-gdb`
is to add the following line to your `~/.gdbinit` (i.e., the `.gdbinit` file
which is in your home directory, **not** `/path/to/pytorch/.gdbinit`):
```
```bash
add-auto-load-safe-path /path/to/pytorch/.gdbinit
```

## CUDA development tips
If you are working on the CUDA code, here are some useful CUDA debugging tips:
Expand Down Expand Up @@ -1119,7 +1125,7 @@ folder (later called `$LLVM_ROOT`).
Then set up the appropriate scripts. You can put this in your `.bashrc`:
```
```bash
LLVM_ROOT=<wherever your llvm install is>
PYTORCH_ROOT=<wherever your pytorch checkout is>
Expand Down

0 comments on commit 71ba76b

Please sign in to comment.