[MISC] Rewrite and update html build instructions

.circleci/config.yml

@@ -2,19 +2,23 @@ version: 2
 jobs:
   build_docs:
     docker:
-      - image: circleci/python:3.8
+      - image: cimg/python:3.8
     steps:
       # checkout code to default ~/project
       - checkout
       - run:
           name: install dependencies
           command: |
+            python -m venv env
+            source env/bin/activate
             python -m pip install --upgrade pip
             pip install -r requirements.txt
-            pip install ~/project/tools/schemacode/
+            pip install -e ~/project/tools/schemacode/
       - run:
           name: generate docs
-          command: mkdocs build --clean --strict --verbose
+          command: |
+            source env/bin/activate
+            mkdocs build --clean --strict --verbose
       - persist_to_workspace:
           # the mkdocs build outputs are in ~/project/site
           root: ~/project
@@ -25,7 +29,7 @@ jobs:
 
   linkchecker:
     docker:
-      - image: circleci/python:3.8
+      - image: cimg/python:3.8
     steps:
       # checkout code to default ~/project
       - checkout
@@ -35,11 +39,14 @@ jobs:
       - run:
           name: install linkchecker
           command: |
-            python -m ensurepip
+            python -m venv env
+            source env/bin/activate
+            python -m pip install --upgrade pip
             python -m pip install linkchecker
       - run:
           name: check links
           command: |
+            source env/bin/activate
             git status
             if (! git log -1 --pretty=oneline | grep REL:) ; then
               chmod a+rX -R ~
@@ -123,7 +130,7 @@ jobs:
   # Run remark on the auto generated changes.md file
   remark:
     docker:
-      - image: node:latest
+      - image: cimg/node:lts
     steps:
       # checkout code to default ~/project
       - checkout
@@ -156,7 +163,7 @@ jobs:
   # Push built changelog to repo
   Changelog-bot:
     docker:
-      - image: circleci/openjdk:8-jdk
+      - image: cimg/base:stable
     steps:
       - setup_remote_docker:
           version: 17.11.0-ce

CONTRIBUTING.md

@@ -306,7 +306,34 @@ before you insert the macro call into the markdown document.
 We are using mkdocs to render our specification.
 Please follow these instructions if you would like to build the specification locally.
 
-#### 1. Install mkdocs, the material theme and the required extensions
+#### 1. Download the BIDS specification [repository](https://github.com/bids-standard/bids-specification/tree/master) onto your computer
+
+This can be done by clicking the green button on the right titled "Clone or
+download"
+or using [this link](https://github.com/bids-standard/bids-specification/archive/master.zip).
+
+Or you can use the following `git` command in a terminal:
+
+```bash
+git clone https://github.com/bids-standard/bids-specification.git
+```
+
+#### 2. In the terminal (command line) navigate to your local version of the specification
+
+This location will have the same files you see on our
+[main specification page](https://github.com/bids-standard/bids-specification).
+Note that a file browser window may not show the hidden files
+(those that start with a period, like `.remarkrc`).
+
+If you cloned the repository using the `git` command above, you can then just do:
+
+```bash
+cd bids-specification
+```
+
+Enter all commands below from the command line prompt located at the root of the local version of the specification.
+
+#### 3. Install mkdocs, the material theme and the required extensions
 
 In the following links, you can find more information about
 
@@ -318,40 +345,41 @@ You will also need several other mkdocs plugins, like `branchcustomization` and
 To install all of this make sure you have a recent version of Python on your computer.
 The [DataLad Handbook](http://handbook.datalad.org/en/latest/intro/installation.html#python-3-all-operating-systems) provides helpful instructions for setting up Python.
 
-An easy way to install the correct version of mkdocs and all the other required extensions
-is to use the `requirements.txt` file contained in this repository,
-by using the following command:
+In general, we strongly recommend that you install all dependencies in an isolated Python environment.
+For example using `conda`, as described in this [Geohackweek tutorial](https://geohackweek.github.io/Introductory/01-conda-tutorial/).
 
 ```bash
-pip install -r requirements.txt
+conda create --name bids-spec
+conda activate bids-spec
 ```
 
-However this will also install some other packages you might not want to have (like `numpy`).
-So if you only want to install what you need to build the specification,
-use the following command:
+Or alternatively using `venv`, as described in this [Real Python tutorial](https://realpython.com/python-virtual-environments-a-primer/).
+
+A short version of the commands needed to create and activate your `venv` virtual environment would look like:
 
 ```bash
-pip install \
- mkdocs \
- mkdocs-material \
- pymdown-extensions \
- mkdocs-branchcustomization-plugin \
- mkdocs-macros-plugin \
- tabulate
+python -m venv env
+source env/bin/activate
 ```
 
-#### 2. Download the BIDS specification [repository](https://github.com/bids-standard/bids-specification/tree/master) onto your computer
+Note that this will create a local directory called `env` within the bids-specification directory
+but that its content will not be tracked by `git` because it is listed in the `.gitignore` file.
 
-This can be done by clicking the green button on the right titled "Clone or
-download"
-or using [this link](https://github.com/bids-standard/bids-specification/archive/master.zip).
+Once you have activated your isolated Python environment,
+an easy way to install the correct version of mkdocs and all the other required extensions
+is to use the `requirements.txt` file contained in this repository as follows:
 
-#### 3. In the terminal (command line) navigate to your local version of the specification
+```bash
+pip install -U pip
+pip install -r requirements.txt
+pip install -e tools/schemacode/
+```
 
-This location will have the same files you see on our
-[main specification page](https://github.com/bids-standard/bids-specification).
-Note: A finder window may not show the hidden files (those that start with a
-period, like `.remarkrc`)
+The first command ensures you are using an up to date version of `pip`,
+and the second command installs all dependencies.
+The third command ensures to install the BIDS schema code as an "editable" install,
+so that if you make changes to the schema files,
+these are automatically reflected in the sourcecode.
 
 #### 4. Ready to build!