Thanks @agriyakhetarpal. Note that the doc build CI is failing. Apologies in advance: I suggested splitting this off from your previous PR, but won't have time to actually review in detail over the next days.

Request to potential reviewers: this PR has the potential for a lot of bikeshedding. In case you are feeling an inclination to actually start such a process, I strongly recommend to think twice before doing that, and read the linked threads under "additional context" first.

Not sure if I understand the "Diverging branches can't be fast-forwarded" error in CircleCI with the 128 exit code. My branch and my commits seem fine, so it's most likely a downtime incident with GitHub.

There was an incident for GitHub repo clones on Friday, which seems to have been resolved today, but there's a different error in CircleCI from conf.py with the line: assert 'numpy._core._add_newdocs_scalars' not in sys.modules. I can't reproduce this locally with spin docs --clean – I'll keep investigating. If someone could re-trigger the CircleCI job for this commit, that would be great (or I can push some commits with further changes).

The docs build has been fixed in main, I updated my branch and I added a few commits for the user guide. Many of the rest of the pages under the user guide are better poised to be converted to Jupytext-based notebooks as discussed in #26745 (comment) (under the "Key changes" section).

Compare with: https://numpy.org/doc/stable/reference/random/index.html

Compare with: numpy.org/doc/stable/reference/random/index.html

I restored this change to the original in 25f9a99. It's not neat, but adding the TryExamples directive will fix this indentation problem.

There is a merge conflict, I guess that is to be expected in a PR this big. Perhaps we could push this over the finish line, and fix any lingering indentation problems in follow-on PRs?

Thanks, @mattip – I resolved the merge conflicts, and this is ready for review again. I, too, suggest fixing indentation problems in follow-on PRs.

Thanks @agriyakhetarpal

I wonder if there is a regex we could use on the rendered documentation to find indentation problems? Looking at the random example with extra indentation it seems the problem is that a <div class="doctest highlight-default notranslate"> ... </div> code block is contained inside a <blockquote>...</blockquote> block. Can we search for excessive use of blockquote?

This is a good idea, I can look into doing this. With this PR merged, I'll resume my work on gh-26745 and fix any cases of improper indentation.