DOC: updated reference guide text for consistency in writing style

[mkg33]

punctuation, minor stylistic issues

Reference issue

What does this implement/fix?

Additional information

[person142]

General question: are we writing down the style rules anywhere? Otherwise people are likely to forget things like "section headings should be lower case".

[person142]

I guess we could add a CI check for some of these things, but that might drive people crazy.

[mkg33]

Yes, @person142, I'm writing down the 'consistency rules' for future maintenance. As for the CI check, it'd sure be useful but, as you point out, might be annoying. Once I've corrected the docs, I'll relay this question to others in my summary.

[rgommers]

@mkg33 so far you've just updated the tutorial and governance/CoC docs, but I thought it'd be good to point out that @brandondavid is working on similar fixed for the stats reference guide specifically in gh-10863. Would be good to make sure you don't do the same files twice.

[mkg33]

@rgommers good thinking! Thanks for pointing this out. I've revised 15 more files but decided against pushing them because I still haven't solved the issue with the previous commits. I've gone through the complete CI check report but still haven't managed to pinpoint the issue. I've paid attention to all backticks, inserting a hyperlink properly, etc. Do you have any idea what could have gone wrong? Sorry for bothering you with this but I can't find the problem myself.

[rgommers]

This is one of the problems with Sphinx, it's hopelessly bad at telling you what the problem may be. I'll try to help later today and if I find the problem, share how I went about debugging it. From the CI build log it's indeed not clear.

[mkg33]

@rgommers thanks a lot. I mean, I hate to bother you with it because I caused this mess but I can't proceed with the commits, so it's probably the right time to ask for help :-) I've already wasted a bit of time on analysing the log several times...

[larsoner]

The HTML seems to complete fine:

...
dumping object inventory... done
build succeeded.

The HTML pages are in build/html-scipyorg.

But the Latex build complains:

Latexmk: Errors, so I did not complete making targets
Collected error summary (may duplicate other messages):
  pdflatex: Command for 'pdflatex' gave return code 256
Latexmk: Use the -f option to force complete processing,
 unless error was exceeding maximum runs of latex/pdflatex.
Makefile:32: recipe for target 'scipy-ref.pdf' failed
make: *** [scipy-ref.pdf] Error 12
make: Leaving directory '/home/circleci/repo/doc/build/latex'
Exited with code 2

So the problem is in pdflatex returning 256. It's probably from this:

./scipy-ref.tex:26660: Missing delimiter (. inserted).
<to be read again> 

So some ref got messed up in scipy-ref.tex. Unfortunately we don't store doc/build/latex as a CircleCI artifact, so I ran the build locally. For me this succeeded but landed on the Wiener filter line:

    y=\left\{ \begin{array}{cc} \frac{\sigma^{2}}{\sigma_{x}^{2}}m_{x}+\left(1-\frac{\sigma^{2}}{\sigma_{x}^{2}}\right)x & \sigma_{x}^{2}\geq\sigma^{2},\\ m_{x} & \sigma_{x}^{2}<\sigma^{2},\end{array}\right,

I would undo this change and see if it fixes things. It already seems to render okay on 1.3.0 at least:

https://docs.scipy.org/doc/scipy/reference/tutorial/signal.html#wiener-filter

[mattip]

Something is off in the CircleCI log for commit 663c2b4 (the last commit). Unfortunately it cuts off the top lines, but downloading the log the first few lines are

Building, see build.log...
    ... build in progress (0:01:00.165203 elapsed)
    ... build in progress (0:02:00.232684 elapsed)
Build OK (0:02:03.736803 elapsed)
make: Entering directory '/home/circleci/repo/doc'
mkdir -p build/html build/doctrees
LANG=C "/home/circleci/repo/venv/bin/python" -msphinx -WT --keep-going -t scipyorg -b html -d build/doctrees  "-j2" source build/html-scipyorg 
Running Sphinx v2.2.0
SciPy (VERSION 1.4.0.dev0+257958d)
making output directory... done
[autosummary] ....

Shouldn't that be the SciPy version under build, which would be the current commit?

[Kai-Striega]

@mkg33 I'm not too sure if having style checks in the CI will work too well. I've been using GNU Style & Diction along with (codespell)[https://github.com/codespell-project/codespell] in a githook. It works with a human to check the mistakes but I'm not sure how well it transfers to CI.

[mkg33]

@larsoner thanks for looking into this; I'll make the change you suggested and we'll see how it turns out. @Kai-Striega I suppose we should avoid the style checks, totally agree. So far, I've noticed that most documentation doesn't suffer from poor grammar / explanations. The only issues are very rare typos and sticking to conventions (plus proper punctuation).

[rgommers]

All right, build_docs is green and the one failure is a CI timeout. Merging. Thanks @mkg33!

[mkg33]

Thanks, @rgommers! I was just about to come back to this issue (tomorrow) and now the problem has solved itself :-)

[rgommers]

No worries. I thought it'd be good to get this in, since PRs like these tend to accumulate merge conflicts.