Fix and update the docs.ovh.com dev environment

Dockerfile

@@ -1,18 +1,22 @@
-FROM python:3.5
+FROM python:3.9.4
 
-ENV SRC=//src
-ENV WORKDIR=//src/docs
+LABEL \
+  maintainer="OVHcloud team" \
+  description="Image used to locally build the docs.ovh.com documentation."
+
+ENV \
+  SRC=/src \
+  WORKDIR=/src/docs
 
 ADD ./src $SRC
-RUN git clone https://github.com/ovh/docs-rendering.git $WORKDIR
+RUN git clone --recurse-submodules https://github.com/ovh/docs-rendering.git $WORKDIR
 WORKDIR $WORKDIR
-RUN mkdir pages
-RUN mkdir output
+RUN \
+  mkdir -p pages output && \
+  pip install -r requirements.txt && \
+  chmod +x $SRC/entrypoint.sh
 
 VOLUME ["$WORKDIR/pages/"]
-
-RUN pip install -r requirements.txt
-RUN chmod +x $SRC/entrypoint.sh
-
 EXPOSE 8080
+
 CMD $SRC/entrypoint.sh

README.md

@@ -1,16 +1,16 @@
-# OVH Docs : Developer environment 
+# OVH Docs : Developer environment
 
 Easy to deploy developer environment, for writing/testing guides & documentations for docs.ovh.com
 
 ## With Docker
 
 ### Prerequisite
 
-- [Docker](https://docs.docker.com/install/) installed
+- [Docker](https://docs.docker.com/install/) installed on your workstation
 
 ### Build script
 
-Show help
+Show help:
 
 ```sh
 ./build.sh -h
@@ -24,85 +24,89 @@ Show help
 
 ```
 
-Start the build
+Start the build:
 
 ```sh
 ./build.sh -f /path/to/docs
 ```
 
-Next, go to http:///localhost:8080/fr/
+Next, go to `http://localhost:8080/fr/`
 
 ### Steps (Manual)
 
-First, build the docker image
+First, build the docker image:
+
 ```sh
 git clone https://github.com/ovh/docs-developer-env.git
 cd docs-developer-env
 docker build -t ovh-docs-dev-env .
 ```
 
-Second, run docker container
+Second, run docker container:
+
 ```sh
 # get the ovh docs repository
 git clone https://github.com/ovh/docs.git
 cd docs
-# run the container and mount volume "pages" (change the port to suit your needs, here XXXXX)
+# run the container and mount volume "pages" (change the port to suit your needs if required)
 # the port 8080 is the exposed one, so don't change it
-docker run --rm -v $(pwd)/pages:/src/docs/pages -d --name ovh-docs-dev-env -p XXXXX:8080 ovh-docs-dev-env
+docker run --rm -v $(pwd)/pages:/src/docs/pages -d --name ovh-docs-dev-env -p ${PORT:-8080}:8080 ovh-docs-dev-env
 ```
 
-__Note__ : the pelican build, started in __debug mode__, takes __1 or 2 minutes__ to complete. 
+__Note__ : the pelican build, started in __debug mode__, takes __1 or 2 minutes__ to complete.
+
+Check the logs:
 
-Check the logs.
 ```sh
 docker logs -f ovh-docs-dev-env
 ```
 
-When the build is complete, go to http://localhost:XXXXX/fr/ and check your works.
+When the build is complete, go to `http://localhost:${PORT:-8080}/fr/` and check your works.
+
+Third, stop the container:
 
-Third, stop the container
 ```sh
 docker stop ovh-docs-dev-env
 ```
 
 ## Without Docker
 
-Use this method only if docker is not an option or for local development
+Use this method only if Docker is not an option or for local development.
 
 1. First, checkout the following repositories
 
 ```shell
 git clone https://github.com/ovh/docs-developer-env.git
-git clone https://github.com/ovh/docs-rendering.git
+git clone --recurse-submodules https://github.com/ovh/docs-rendering.git
 ```
 
 2. Then, you'll need to prepare and install the dependencies
 
 ```shell
 cd docs-rendering
-python3 -m venv venv3  			# create a virtualenv
-. venv3/bin/activate  			# enter the virtualenv
-pip install -r requirements.txt	# install dependencies
-mkdir output  					# prepare the destination directory
+python3 -m venv venv3           # create a virtualenv
+. venv3/bin/activate            # enter the virtualenv
+pip install -r requirements.txt # install dependencies
+mkdir output                    # prepare the destination directory
 ```
 
-**Option 1: full documentation**
+- Option 1: full documentation
 
 ```shell
 cd .. && git clone https://github.com/ovh/docs.git; cd -
-ln -sf ../docs/pages .  		# prepare the source directory
+ln -sf ../docs/pages . # prepare the source directory
 ```
 
-**Option 2: local guide edition**
+- Option 2: local guide edition
 
 ```shell
-cp -r ../docs-developer-env/stub/ pages	# copy a minimal set of file to get you started
+cp -r ../docs-developer-env/stub/ pages # copy a minimal set of file to get you started
 ```
 
 3. Finally, without changing of directory
 
 ```shell
-../docs-developer-env/src/entrypoint.sh  # start pelican and the web-server
+../docs-developer-env/src/entrypoint.sh # start pelican and the web-server
 ```
 
-and navigate to `http://localhost:8080/`
+and navigate to `http://localhost:8080/`.

src/entrypoint.sh

@@ -7,8 +7,7 @@ SRC_DIR=$BASEDIR/pages
 OUTPUT_DIR=$BASEDIR/output
 CFG_FILE=$BASEDIR/pelicanconf.py
 
-cd $BASEDIR;
-$PELICAN --debug --autoreload -r $SRC_DIR -o $OUTPUT_DIR -s $CFG_FILE &
-pid=$!
-cd $OUTPUT_DIR;
+cd "$BASEDIR" || exit;
+$PELICAN --debug --autoreload -r "$SRC_DIR" -o "$OUTPUT_DIR" -s "$CFG_FILE" &
+cd "$OUTPUT_DIR" || exit;
 $PY -m pelican.server 8080