docs: amend makefile command; address warning

[sadielbartholomew]

Close #2950 & also amend an RST format title underline which is a character too short, introducing a sphinx-build warning [.../site-user-config-ref.rst:183: WARNING: Title underline too short.].

With this PR, running both the explicit cylc make-docs command & make (in the overarching i.e. $CYLC_DIRdirectory) will build the docs cleanly.

[kinow]

Isn't that Cylc, as in Cylc project? Just out of curiosity, because I normally use Cylc for project name, and cylc for command name.

[sadielbartholomew]

True, I agree it should really be the capitalised form in general, so I originally went in to change another line nearby, but then I saw that all nearby content used the lower-case variant. I then did a quick skim through a sample of the rest of the docs, where the lower case seemed to be used.

So I made this change for consistency. Sorry, I probably should have clarified that in the opening comment. (As an aside I am not quite pedantic enough to go through & via grepping & checking blitz the entire docs to convert non-command etc. references from cylc to Cylc, even if that is preferred!)

[kinow]

Not a problem. Thanks for clarifying Sadie!

[hjoliver]

I originally wrote "Cylc" (the project) as "cylc" too, but was eventually persuaded by a manager that it stands out more in documents if capitalized. But there's still a mix of cases in the user guide (my fault!).

[kinow]

Looks good to me. Tried cylc make-docs and it worked fine, without any warnings/errors. It's also quite quick.

Only interesting that I didn't have sphinx-build the first time I ran it, but it still took a while doing something. Or at least it said generating the command reference.

Maybe it would be sensible to fail quick if no sphinx-build in the $PATH?

Oh, also confirmed that the ^^^..^^^ fixed the only warning I had building in master.

Added one comment about a word used, but not a blocker IMO. 👏

[sadielbartholomew]

Only interesting that I didn't have sphinx-build the first time I ran it, but it still took a while doing something. Or at least it said generating the command reference.

Ah yes, very good point! I noticed that too during the docs conversion, but never thought to go in & rectify it given a large checklist of items to get right for the docs conversion. Regrettably, as it would have ultimately saved me time!

It is the simply that the command reference RST file needs to be generated from the command docstrings / --help content via make-commands.sh, and that needs to be run before the sphinx-build else it will fail on a missing file.

Maybe it would be sensible to fail quick if no sphinx-build in the $PATH?

This sounds like a good way to get around the issue. Feel free to add that in to cylc make-docs if you feel it is worth it, though it might not be depending on how soon we can, as discussed, replace that command with a build via setup.py...