[MISC] Rewrite and update html build instructions

[sappelhoff]

closes #1030

This is changing the order of instructions:

• first clone
• then navigate to the spec
• then install python via requirements.txt

that's important because we have the schema package, which is local -- so navigating to the local dir of the spec ensures success.

Furthermore I recommend using an isolated python environment -- that way we can do without the "special instructions" in case somebody doesn't want numpy (in an isolated env it doesn't really matter if they have numpy or not).

[Remi-Gau]

Nice to see we had the same idea about the main changes to make without talking about it. 🤗

Also added basic snippet to clone and set up the environments because I tend to get annoyed by tutos or set up instructions that say, "to do step 1, read this other 30 000 words tuto".

[Remi-Gau]

Good to go

[mateuszpawlik]

I think this issue fits here. When I modified README description in src/schema/objects/top_level_files.yaml neither mkdocs serve nor mkdocs build --clean --strict --verbose would build the modified version. Executing pip3 install --upgrade tools/schemacode/ helped. I find it weird.

[sappelhoff]

That's a bit weird indeed - I clarified with Taylor (who is the expert on everything schema related) and he couldn't replicate your issue. Furthermore, the CI pretty much runs the same code as you, and there the changes also appeared in the build output.

bids-specification/.circleci/config.yml

Lines 6 to 24 in 88a9730

	steps:
	# checkout code to default ~/project
	- checkout
	- run:
	name: install dependencies
	command: |
	python -m pip install --upgrade pip
	pip install -r requirements.txt
	pip install ~/project/tools/schemacode/
	- run:
	name: generate docs
	command: mkdocs build --clean --strict --verbose
	- persist_to_workspace:
	# the mkdocs build outputs are in ~/project/site
	root: ~/project
	paths: site
	- store_artifacts:
	path: ~/project/site/
	destination: dev_docs

Perhaps that's some idiosyncratic issue on your system/setup OR you maybe did a mistake somewhere? Anyhow, if you have a concrete suggestion what to improve, please let me know :-)

[mateuszpawlik]

I tried it again carefully from scratch.

1. Create venv, build and serve. Everything works as expected.

python3 -m venv mkdocs-env
source mkdocs-env/bin/activate
pip3 install --upgrade pip
pip3 install --requirement requirements.txt
mkdocs build --clean --strict --verbose
mkdocs serve

2. Modify a file, build, serve and see the changes. No changes generated.

vim src/schema/objects/top_level_files.yaml
...
mkdocs build --clean --strict --verbose
mkdocs serve

Removing site directory and building again doesn't help.

My versions of the Python packages:

Package                           Version
--------------------------------- -----------------
click                             8.0.4
ghp-import                        2.0.2
gitdb                             4.0.9
GitPython                         3.1.27
importlib-metadata                4.11.3
Jinja2                            3.0.3
Markdown                          3.3.6
MarkupSafe                        2.1.1
mergedeep                         1.3.4
mkdocs                            1.2.3
mkdocs-branchcustomization-plugin 0.1.3
mkdocs-macros-plugin              0.6.4
mkdocs-material                   8.2.6
mkdocs-material-extensions        1.0.3
numpy                             1.22.3
packaging                         21.3
pandas                            1.4.1
pip                               22.0.4
pkg_resources                     0.0.0
Pygments                          2.11.2
pymdown-extensions                9.3
pyparsing                         3.0.7
python-dateutil                   2.8.2
pytz                              2022.1
PyYAML                            6.0
pyyaml_env_tag                    0.1
schemacode                        1.7.0+21.g559551f
setuptools                        44.1.1
six                               1.16.0
smmap                             5.0.0
tabulate                          0.8.9
termcolor                         1.1.0
watchdog                          2.1.6
zipp                              3.7.0

I couldn't find any related issue in https://github.com/fralau/mkdocs_macros_plugin/

[mateuszpawlik]

I think I've found the problem. The tools/schemacode/ package is installed with the data directory, where a copy of the schema resides. In my case mkdocs-env/lib/python3.9/site-packages/schemacode/data/schema/objects/top_level_files.yaml has the content from the moment of installing tools/schemacode/. My guess is, that schemacode's version of the schema content is used whenever mkdocs build is executed.

I changed the content of mkdocs-env/lib/python3.9/site-packages/schemacode/data/schema/objects/top_level_files.yaml file and changes are reflected after mkdocs build.

[effigies]

You can also use pip install -e to install a package in editable mode.

[sappelhoff]

Thanks @mateuszpawlik for investigating, that makes sense ... I hadn't thought of that. I took Chris' solution and added it as a commit to the contributor instructions.

[sappelhoff]

Failures are due to Jinja2 3.1 release 30 minutes ago:

• https://jinja.palletsprojects.com/en/3.1.x/changes/#version-3-1-0
• https://pypi.org/project/Jinja2/#history

EDIT: see also mkdocs/mkdocs#2794