Add docs preview and build

[philderbeast]

I previewed the docs locally for #6603. I couldn't find how to do this in CONTRIBUTING.md so added a makefile recipes for previewing and building the docs.

• [ ] Any changes that could be relevant to users have been recorded in ChangeLog.md.
• [x] The documentation has been updated, if necessary

[mpilgrem]

@philderbeast, that is mostly explained in the linked MkDocs documentation. Historically, the Stack repository has not sought to duplicate that. See https://www.mkdocs.org/getting-started/.

If you think the MkDocs project's documentation is hard to follow, we could spell out the steps in CONTRIBUTING.md.

However, I'm not keen on guidance that assumes users already have the make tool on the PATH. Neither Windows or the Stack-supplied MSYS2 environment provides it 'out of the box'. Especially as the steps are simple:

• Prerequisties:
  • install Python 3 on your system
  • install the required Python packages, with pip install -r doc/requirements.txt (see that file for those packages)
• Preview documentation as you work on it, by using the mkdocs build-in server:
  • in Stack's project directory, command mkdocs server

[philderbeast]

@mpilgrem it took me 5-10 mins to write the docs for #6603 but it took me about an hour to work out that Stack CI doesn't provide a readthedocs preview for a pull request and to get the mkdocs preview working locally. I definitely needed some kind of preview to get the formatting correct.

If this pull request will save a Stack docs contributor time then it is worth it, isn't it? There's no negative consequence on those that don't want to use the Makefile is there?

[philderbeast]

• Prerequisties:

  • install Python 3 on your system
  • install the required Python packages, with pip install -r doc/requirements.txt (see that file for those packages)

• Preview documentation as you work on it, by using the mkdocs build-in server:

  • in Stack's project directory, command mkdocs server

Doesn't the pip install make a global install? Isn't using a virtual environment a less polluting way to get the dependencies?

Here's an error I was getting:

$ mkdocs server
Traceback (most recent call last):
  File "/~/.local/bin/mkdocs", line 5, in <module>
    from mkdocs.__main__ import cli
ModuleNotFoundError: No module named 'mkdocs'

[mpilgrem]

I'm not adverse to the make tool full stop, only to guidance that assumes that users already have make on the PATH. Also, by way of context, there are three things that I am trying to do more generally:

1. Consistent with the Stack project's stated goals, make the Stack experience (including documentation) 'operating system agnostic' - at least as regards Windows, macOS and the most popular Linux distributions.
2. Reduce the level of 'assumed knowledge' in guidance. My mental model is that guidance should be accessible to somebody who has completed secondary education and is contemplating studying computer science in further or higher education. In that regard, I think it is reasonable to assume many Stack users will have come across Python (as it has become ubiquitous, including in secondary education), but not reasonable to assume that they will know what is make.
3. Keep things 'within the [Haskell and Stack] family'. So, for example, I would favour a solution that used a Haskell script - perhaps making use of the shake project. The Stack project uses Haskell scripts and shake elsewhere. Partly that is because introducing something like make introduces an additional maintenance 'cost'.

In terms of tools, the Stack-supplied MSYS2 does provides the sh executable 'out of the box', so sh scripts, run in the Stack environment, are accessible cross-platform and meet my first objective.

[philderbeast]

Whether it is a Makefile or a Shake script, having it there means that the steps involved can be inspected.

PYTHON_VIRTUALENV:=.python-doc-virtualenv
MK_DOCS_CMD:=$(PYTHON_VIRTUALENV)/bin/mkdocs

../$(PYTHON_VIRTUALENV)/bin/activate:
    python3 -m venv ../$(PYTHON_VIRTUALENV)
    (. ../$(PYTHON_VIRTUALENV)/bin/activate && pip install -r requirements.txt)

docs-serve: ../$(PYTHON_VIRTUALENV)/bin/activate
    cd .. && $(MK_DOCS_CMD) serve

docs-build: ../$(PYTHON_VIRTUALENV)/bin/activate
    cd .. && $(MK_DOCS_CMD) build

I started using shake 10 years ago but for this small automation I prefer make. That's with less experience in make. I only started writing recipes in make myself in 2023. That's said, I'm happy to convert this to shake if you prefer it that way.

[mpilgrem]

OK, I'll merge this and add an explanation of what the files are as a separate step. EDIT: guidance added in 32e48ee8048264f6a19d5f352744400470e2c36e and 062cb8f900642c5f8475ce89b87920b8bba65524.