Build failed but the uploaded docs are mostly correct

Moving the discussion from #21224 (comment) to here.

BTW, I'm open to inverting #21251 and moving all the references to /contents.html and getting rid of /users/index.html.

Makes sense.

We could probably just rename /users -> /miscellaneous which is what is in that directory now.

I think the folder structure here dictates the url structure in the final docs. Having miscellaneous/installing.html is a bit weird. Maybe we have to move documents around as well.

In theory the main sections in https://63987-1385122-gh.circle-artifacts.com/0/doc/build/html/users/index.html should correspond to top-level file structure elements; single files like ressources (if there is only one file containing the whole section) or folders like gallery.

OK, I've persisted here in keeping /users/index.html as the top-level TOC. We could bubble it up a level, but I really prefer the tree with /doc/gallery, /doc/tutorials, /doc/api, /doc/users as the only top-level subdirectories. Basically /doc/users is the rst-based docs, appropriately sorted, and the other three are auto-generated. (The exceptions are the development guide and thridparty, both of which will be hosted separately).

nit: under install Third-party distributions is I think mpl specific jargon, what about package manager or Installing using a package manager

Thanks @story645 - that is what is in the current Installing guide, so I was just copying verbatim. I've tried to keep editorial changes out of this PR because it touches so much of the website we'd be quite a while fixing everything!

I can make it it's own PR then...

@timhoffm @tacaswell not quite sure if se decided to move all the rst up a level or not. I think that would be

- doc/
  - backmatter
   - explain
   - faq
   - installing
   - next_whats_new
   - prev_whats_new
   - resources  
   - tutorials
   - examples
   - plot_types
   - api
   - thirdparty 
   - devel
   
   - index.html (current docs top page)
   - contents.html (what is currently users/index.html

I'd still prefer the Navbar links linked to topic/index.html if possible, but ..

This is a link to the new TOC of users/: https://64359-1385122-gh.circle-artifacts.com/0/doc/build/html/users/index.html#