DOC: Reorder first two tutorial sections

[drammock]

This puts the first two sections of the tutorials in fixed order, by introducing digits into their filenames. It also changes all cross-refs targeting those files to use :ref:-style crossreferences instead of :doc:-style ones (excepting documentation.rst, which refers to generated .rst files rather than cross-ref anchors).

Note: I had originally been preferring :doc:-style cross-refs because :ref:-style links to the page title will load the page already scrolled down a bit, thereby hiding the "this is the dev version" banner... but the benefit of not having to re-do the crossrefs if a filename changes seems worth that cost.

[larsoner]

This puts the first two sections of the tutorials in fixed order, by introducing digits into their filenames. It also changes all cross-refs targeting those files to use :ref:-style crossreferences instead of :doc:-style ones (excepting documentation.rst, which refers to generated .rst files rather than cross-ref anchors).

An alternative would be to name the files whatever is sensible, then tweak the Sphinx-gallery config to reorder sections in the doc/conf.py. This would probably get the best of both worlds, meaning good file names and also good static links.

[larsoner]

https://sphinx-gallery.github.io/configuration.html#within-gallery-order

You can always make your own sorter. The API is not publicly documented but you can probably figure it out from looking at the code

https://sphinx-gallery.github.io/_modules/sphinx_gallery/sorting.html#NumberOfCodeLinesSortKey

Basically for each src_dir a new class is instantiated. Then it gets called with each filename and must return something that sorted can operate on, usually an int. So in your case you could have a dict where each src_dir is a key, and each value is the filenames in the order you want. If src_dir is in the dict, you just return my_dict[self.src_dir].index(fname) in the __call__. (And if src_dir is not in the dict in doc/conf.py, you can fall back to using one of the SG sorters so you don't have to start out enumerating all file names in all tutorials and examples.)

[drammock]

@larsoner I did look at making a custom sorter a few months back, and I'm not convinced it's better here. With my "stick a number in the filename" solution, the effect on sorting is self-evident at the time any future filename or location change is being made. If I use a custom sorter, then changing a filename will necessarily cause problems if the custom sorter is not also updated (at best, it will punt the renamed file to the end of the sorting), which seems like creating extra work for future contributors.

I realize that the filename looks ugly now, but once this is done for all sections I also hope to do the sphinx-gallery regex hack so that the filenames don't have to all start with plot_ anymore; when that happens it will be less ugly (10_overview.py instead of plot_10_overview.py)

[codecov]

Codecov Report

Merging #6489 into master will decrease coverage by 80.86%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #6489       +/-   ##
==========================================
- Coverage   89.23%   8.37%   -80.87%     
==========================================
  Files         413     399       -14     
  Lines       74528   73536      -992     
  Branches    12300   12259       -41     
==========================================
- Hits        66508    6155    -60353     
- Misses       5162   67324    +62162     
+ Partials     2858      57     -2801

[larsoner]

Thanks @drammock