Issues building site with fresh repository clone on MacOS

[euphemism]

Hey there,

Submitted a pull request here: #165, but getting the site built wasn't as straightforward as the README currently suggests.

The first of my issues is that running make page results in the following error:
ModuleNotFoundError: No module named 'pandocfilters'. What the README does not inform would-be contributors of is that the following prerequisites need to be met:

• Python is installed
• The pandocfilters module is installed globally

I would suggest updating the README to let people know Python is required and subsequently looking into virtual environments to both version control the list of necessary packages, and enable modifying the Makefile to instantiate the virtual environment before running the page target.

I am assuming development has only happened on Linux machines, as after fixing the pandocfilters issue, running make page results in the following error:

cp assets/ out -r
cp: -r is not a directory

from this line in Makefile.

cp seems to behave differently on BSD/MacOS or something. I had to change the command to the following for the build to succeed:

cp -R assets out

So making sure this is a cross-platform compatible operation would be helpful. I believe this variation on the command works on both MacOS and Linux.

[JohnTitor]

Since this website is rarely updated, we haven't documented everything, sorry about that.

About the first issue, I agree that these requirements should be listed.

cp seems to behave differently on BSD/MacOS or something. I had to change the command to the following for the build to succeed:

cp -R assets out

So making sure this is a cross-platform compatible operation would be helpful. I believe this variation on the command works on both MacOS and Linux.

I don't have a macOS env and I cannot confirm what's command correct here, but indeed -R works as same as -r on my env (Linux), so your suggestion should be correct.

Could you open a PR to document them?

[weiznich]

Fixed by #168 and #169

[euphemism]

Still need to mention Python requirement in the README I would think. Will open a pull request for that today.

[Sytten]

I got this error on a clean make page

$ make page
python3 -m venv ./.venv
./.venv/bin/python -m pip install --upgrade pip setuptools wheel
Requirement already satisfied: pip in ./.venv/lib/python3.11/site-packages (23.0.1)
Collecting pip
  Using cached pip-23.3.1-py3-none-any.whl (2.1 MB)
Requirement already satisfied: setuptools in ./.venv/lib/python3.11/site-packages (67.6.1)
Collecting setuptools
  Using cached setuptools-69.0.2-py3-none-any.whl (819 kB)
Collecting wheel
  Using cached wheel-0.42.0-py3-none-any.whl (65 kB)
Installing collected packages: wheel, setuptools, pip
  Attempting uninstall: setuptools
    Found existing installation: setuptools 67.6.1
    Uninstalling setuptools-67.6.1:
      Successfully uninstalled setuptools-67.6.1
  Attempting uninstall: pip
    Found existing installation: pip 23.0.1
    Uninstalling pip-23.0.1:
      Successfully uninstalled pip-23.0.1
Successfully installed pip-23.3.1 setuptools-69.0.2 wheel-0.42.0
./.venv/bin/pip install -r requirements.txt
Collecting pandocfilters==1.5.0 (from -r requirements.txt (line 1))
  Downloading pandocfilters-1.5.0-py2.py3-none-any.whl (8.7 kB)
Installing collected packages: pandocfilters
Successfully installed pandocfilters-1.5.0
touch ./.venv/bin/.initialized-with-Makefile.venv
mkdir -p out/./
. ./.venv/bin/activate && pandoc -t html5 --template=template.html -F code-block-filter.py src/index.md -o out/index.html -s --syntax-definition=toml.xml --highlight-style=diesel.theme
/bin/sh: pandoc: command not found
make: *** [index.html] Error 127

EDIT: Ha, it needs an OS pandoc (brew install pandoc)

[euphemism]

Context and potential pip-based solution:

https://stackoverflow.com/questions/62398231/building-docs-fails-due-to-missing-pandoc

https://pypi.org/project/pypandoc-binary/