Fix #2687: scripts/makedocs now checks that required software is installed

[LeeTibbert]

Issue #2687 was closed because it looked at the time like a solution would
be a long time coming. With the pending release of Scala Native 0.5.0-?? Real Soon Now,
it would be nice if the new developers it attracts could document their changes
and visually check the results.

This PR modifies scripts/makedocs to check that software used to build the documentation
is available on the system doing the building. make, python, pip, sphinx-build are all checked.

Installing the now required 'sphinx_last_updated_by_git' manually is not for the faint of heart.

[LeeTibbert]

@ekrich

I believe that you have a long standing and continuing interest in this area. I believe there
a number requests for your time these days. If you have time and interest, could you take a look
at this? It is not a total or end-all solution, but it should make it easier for people, like me,
to bootstrap.

I re-worked some of your prior work in the Contributor's QuickStart page.

I understand if you are flat-out and do not have time.

Thanks

[WojciechMazur]

Maybe better keep using paths relative to project root directory

[LeeTibbert]

Thank you for looking at this.

In general, I concur that things like scripts/makedocs should, after the first mention of
from project root directory, be assumed and documented as relative.

To the best of my knowledge a file: URL scheme has to be a fully qualified path. I think having a
working example makes it easier for devos who do not use file URLs regularly to check their work.

As always, I am open to alternate wording.

[tanishiking]

I'm thinking having a dockerfile to install prequired software for builing docs, wdyt?

[LeeTibbert]

re: dockerfile

I think that anything that makes it easier devos, especially new or returning ones, to build the documentation
is worthwhile, if it can be done in economic time (weeks, not months) and if the description of it is shorter or
more comprehensible than what it replaces.

We are probably on the same page that good, lightly commented, code is the best documentation and
that sometimes words provide an easier or faster point of entry.

If you take a run at this, I am willing to exercise anything you come up with.

Now that I can build docs on one system, I am set for as long as that hardware remains healthy.
So the motivator is being a welcoming community member.

[LeeTibbert]

IIUC Docker can run on Windows. That would expand our capabilities.

Not running on Windows is OK, but a nice to have (if cheap). Right now,
I think it unclear, at least to me, if the SN doc build is supposed to run on
Windows. I am in the low priority process of trying to figure that out, and
then document it in the Contributor's Guide so that rapid readers can
set their expectations. Much as I hate to admit it, not all the world is
unix-like.

[LeeTibbert]

IIUC a dockerfile still has the bootstrap concern that Docker must be installed. So probably
means a script that checks that Docker is installed and then runs the dockerfile with
desired options. Doable, but a detail. You are probably way ahead of me on this.

[JD557]

For future reference, here's how I built the docs on Windows without WSL:

python -m venv .venv
.venv\Scripts\activate
cd .\docs\
pip install -r requirements.txt
sphinx-build -b html -d _build/doctrees . _build/html

The main differences from the original script being:

• I don't have bash, so I had to run all commands manually
• For some reason, Python's .venv dir had a Scripts directory instead of bin
• I don't have make, so I had to call sphinx-build directly

[LeeTibbert]

I propose that this PR be merged on the basis of
"better than what went before, but has known deficiencies and alternatives".

Just today I went to build the docs for a proposed PR and ran afoul of missing software.
Teach me to write or edit documentation.

[ekrich]

Couldn't we have a bat file for Windows and a shell script for UNIX like. The added dependency was missing. We also need the script to support clean.

[LeeTibbert]

re: Windows

My interest in Windows is so that the Contributor's Guide can say what we do and
do not support. Perhaps when I am rested I will fold in the information JD557 provided.
If this gets merged before I can get to that, perhaps a doc only PR after that.

re: clean
clean is a good idea but, I think, a requirement for another iteration.

Discussions and review such as this help bring out what is useful, so one can design "the good",
but requirements can also exceed resources.

Deletion is always tricky. The Sphinx make file supports clean already.

The .venv file can take a lot of dead space and currently gets left behind.
If one is doing a number of builds in a row, that is helpful. Leaving
it around for 6 months or years can build up over projects.

If the dockerfile idea gets implemented, even as an experiment, it will be
interesting to see its "Look & feel".

[tanishiking]

Opened a PR to build the docs using Docker instead of setting up the dev environment locally #3781 does it solve the issue?

[ekrich]

We could use that to build docs in CI.

[ekrich]

I am not super excited about the dockerfile approach. I think having a Windows batfile like above and fixing up the sh script version should be fine. I am not too concerned about the .env file as that seems like a small issue.

[JD557]

Personally, I would also prefer a .bat/.ps1 instead of a dockerfile.

If I need to run that on a dockerfile on windows, I might as well run it using WSL.

[tanishiking]

I personally don't like complicating the script file just for running sphinx and prefer docker to reproducible.build, but not a strong opinion.

[tanishiking]

(TBH, I think even a makedocs script can be deleted and adding an instruction to docs how to build the doc is sufficient

like #3778 (comment)

[ekrich]

Well a docs script and bat file could at least call this.

sphinx-build -b html -d _build/doctrees . _build/html

[LeeTibbert]

I'm marking this as draft and pulling it off the mainline onto a spur.

It will be awhile before I am able to study & exercise PR #3781.
Zip is not as simple as it appears.

I think the ideas introduced in this PR of having a README in the docs directory, even
if it only points to the relevant section in the Contribuitor's Guide is worthwhile.

I also think that having a section in the Contributor's Guide which describes how
to build the docs on Windows is worthwhile. A cut & paste of the instructions above
would satisfy me.

I do not have the skill (or interest) to create a Windows .bat file. I also do not want
to discourage someone who might be able to create such.

[LeeTibbert]

I do think that a script should check, or at least announce, what software is required.

I have been building the software successfully on my system for years. One day I went
to build it and it failed horribly. Turns out it was because of a bump in the night, or rather
several, and now pip was required inorder to fetch a now required git-last-updated module.

I did not have pip on my system and the documented makedocs failed miserably (with
messages about a missing .venv.) My feelings & words at that time set back my karmic
progression by many species.