

TITLE
[make docs] please help make the validation process easier

COMMENTS
8

REACTIONS
+1: 0
-1: 0
laugh: 0
hooray: 0
heart: 0
rocket: 0
eyes: 0

BODY
Writing serious documents in .rst is such a pain because the sphinx builder is terrible at times. 

If all goes well I can incrementally run `make docs` and it rebuilds just the modified page which is relatively quick, while it still re-runs highlighting on all pages (not needed for the doc I'm working on)

But if a single error happens it rebuilds everything from scratch which takes forever and chances are that it fails again are very high. since half the time I have no idea what the error is. It's good if it even tells me the line number but sometimes it doesn't even give any context - what a horrible tool. So I have to do a lot of guessing and a lot of waiting and by the end of it I don't really want to finish the doc I was very inspired to write.

There must be a better way to isolate just the page I'm working on. I don't care for cross references, I just want to be able to quickly validate that my page will "compile" and not error.

For example how do I hack `make docs` to not do die on:
```
Warning, treated as error:
```
This is extremely painful, as after each error it rebuilds everything which takes forever.

I think what would ease the process in this particular situation is to leave warnings as warnings only make them errors when I commit, and obviously on CI. So something that:

* doesn't treat warnings as errors
* doesn't rebuild everything if something failed in the previous run
* doesn't re-run highlighting on all pages
* ideally a way to work on just one page of my choice - surely it could detect the only modified file - but if it's too much to ask I would be happy to manually supply it

Something like:
```
utils/checksingledoc.py file.rst
```
I don't know sphinx, so it's very hard for me to know what to propose. Perhaps it could build a project made of a single file (or several files) on the fly and that it could solve the problem? Of course, it will need to ignore cross-references as those won't be available and probably other features that I didn't think of.

Or perhaps there is an existing 3rd party program that lints .rst in the same way shpinx does and could be configured to do things that will make the doc writing easier?

Thank you!

@sgugger 