This is an example of how the documentation renders in build html:

That looks great, but I think it would be much better to add scripts that can be used to generate the images at build time instead of checking them in to the repo as they are now. Can you please try that? This has a few benefits, like allowing us to change the style of the plots easily. Thanks!

great improvements, thanks a lot.

I dont think adding scripts used to generate the images at build-time is THAT necessary. If you have them lying around, it'd be great to check them in, but if not we'll make do what the images as-is.

Thanks for the PR. This helps with #5432 and the PR #5450.

Thank you all for the feedback. I checked the script in.

Being new to the project, I'm not familiar with build conventions. In particular, please let me know whether:

• There is a better place for the script (I created a new directory source/scripts)
• Whether the images should build directly to docs/build and/or be part of the Makefile process.

I personally prefer both the simplicity of just having the script but still having the images check in and not adding another build step:

• For new developers, it's helpful to have this sort of documentation when browsing on github
• The script takes a moment to run, and I'd rather not slow down the build process
• The Makefile is very simple right now, and these are the sorts of things which end up complicating it as they build up
• The script depends on pylab, and I don't know whether we want the extra dependency

Thanks a lot, this will be very useful.

• source/scripts should work fine.
• no, let's keep them generated just like they are now (so they should run before the docs are built). It should be easy to extend the Makefile to run the python script before it runs sphinx (I think it's enough to add it before this line).

It's generally best to avoid checking in images, because git is pretty bad at handling binary data (the repo size gets much larger, and everyone has to download the images).

• It's not this bad, this part is executed only when a commit is pushed to master, and shouldn't bottleneck the infra (as long as it finishes within let's say a minute)
• It's just a single line that has to be added to Makefile
• PyTorch can be still built without pylab, it's just for the docs. Few people are building the docs locally, since they're generally available online.

I removed the images and added to the Makefile, as per your preferences. I modified the build scripts to skip over images which had already been built, which is good practice regardless, so it shouldn't add much to time.

Regarding building docs locally, I'm more concerned about any local tools which interpret docstrings (IDEs, etc.). It'd be nice to have that just work. But half a meg is a decent chunk to add to a git repo, and that can grow if we decide to add illustrations more places. I take your point, though. git is surprisingly bad at handling bigger files ("surprisingly" since the data structures it uses scale to big files just fine).

For reference:

• The images, uncompressed, are 525k
• The images, recompressed losslessly with trimage, are 352k. Lossy compression depends on the setting
• The repository is 40M for pytorch, 52M with submodules
• The repository once built is 2.6G
• Rebuilding the images takes 3.5 seconds
• Skipping over built images takes 1 second (load Python imports)
• Rebuilding HTML pages without images takes 11.8 seconds

Oh I didn't see this PR and wrote the RReLU doc myself in #5459 . I can remove my changes so these two PRs won't conflict (hopefully). However, I have two comments on the RReLU doc:

1. it should be ax rather than x/a.
2. nit: there should be a comma after equation and ``where'' should be lower case.

Also this is great improvement, thanks!

@ssnl Good catch! That could have been embarrassing. I took formula from a source which divided by three rather than multiplying by 1/3. Fixed. "Where" is lower-case.

The comma, in the interests of consensus, I added as you suggested. I think it is clearer without (and most parts of the documentation appear to omit it). I added on the second line, since otherwise it typeset very poorly (vertical center and far-right)

@pytorchbot test this please

@pmitros Looks great, thanks!

@ssnl I looked over your PR. On the whole, your text is better than mine. I apologize for not noticing you were working on it. I merged the text. Please feel free to tweak further in your PR.

@pytorchbot test this please

@pmitros It was my bad. :) Thanks for merging the text. I'll rebase my PR on top of yours when it is merged.

@pytorchbot retest this please

Thanks a lot @pmitros!