Merge pull request #279 from fakoor/fix-buster-reference

Refactor notes. Keep content up to date with Buster and LTS 1.2.5

2 files changed, 37 insertions, 16 deletions

diff --git a/README.md b/README.md
index 67b90b43..5594baae 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ Required Debian Packages:
 Debian, requires some extra steps for 
 installing `sphinx`, `sphinx-autobuild` and `sphinx-rtd-theme` packages:
 
-First ensure that phython3 is the default:
+First ensure that phython2 & phython3 are installed and phython3 is the default:
 ```bash
 python --version
 ```
@@ -35,19 +35,35 @@ Alternatively, to make python3 the default, revise the following line to
 point to the relevant 3.x version of the binary on your system:
 
 ```bash
-sudo update-alternatives --install /usr/bin/python python /usr/bin/python3....
+sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 0
 ```
 
 Then follow these steps to install sphinx group of packages: 
 ```bash
 sudo apt-get install python3-sphinx
-sudo apt-get install python3-sphinx-rtd-theme
 ```
 
-To build the html, start a webeserver, and view the output:
+Although mostly everything uses phython3, But to install this specific 
+package, make sure that pip points to the python2 version of the package manager:
+
+```bash
+python --version
+```
+
+Then run:
+
+```bash
+sudo pip install sphinx-rtd-theme
+```
+
+
+Do the following to  build the html and start a webeserver:
 * Run `make livehtml` inside the `docs` folder
-* Browse to http://localhost:8000
 
+Then, to view the live output:
+* Browse to http://localhost:8000
+Note: The changes you save to the sources are represented in the live HTML outout 
+automatically (and almost instantly) without the need to rebuild or refresh manually.
 
 ## Docker
 
diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst
index d72f4b07..c9e48b53 100644
--- a/docs/contributing/build-vyos.rst
+++ b/docs/contributing/build-vyos.rst
@@ -66,9 +66,9 @@ The container can also be built directly from source:
 .. note:: The container is automatically downloaded from Dockerhub if it is not
    found on your local machine when the below command is executed.
 
-.. note:: We require one container per build branch, this means that the used
-   container in ``crux`` and ``current`` can and will differ once VyOS makes
-   the move towards Debian (10) Buster.
+.. note:: Since VyOS has switched to Debian (10) Buster in its ``current`` branch,
+   the that the used is different from the one used for ``crux`` branch. Hence you
+   will need one separate container for each branch
 
 .. _build_iso:
 
@@ -90,10 +90,21 @@ After cloning, change directory to the ``vyos-build`` directory and run:
 .. code-block:: none
 
   $ cd vyos-build
-  $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build bash
+  $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash # for the LTS version
+  $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build bash # for the current version
+
+Note: The above command is used to select the container you want to run (for building the branch you are
+interested in). this selection  is performed by:
+image:
+
+* Using ``vyos/vyos-build:crux``  for VyOS 1.2 (crux) 
+* Using ``vyos/vyos-build`` for the latest image at the moment.
+
+Then 
+.. code-block:: none
   vyos_bld@d4220bb519a0:/vyos# ./configure --architecture amd64 \
                                --build-by "your@email.tld" \
-                               --build-type release --version 1.2.0
+                               --build-type release --version 1.2.5
   vyos_bld@d4220bb519a0:/vyos# sudo make iso
 
 When the build is successful, the resulting iso can be found inside the ``build`` 
@@ -103,13 +114,7 @@ directory.
    as docker does not expose all the filesystem feature required to the container.
    Building within a VirtualBox server on Mac or Windows is however possible.
 
-To select the container you want to run, you need to specify the branch you are
-interested in, this can be easily done by selecting the appropriate container
-image:
 
-* VyOS 1.2 (crux) use ``vyos/vyos-build:crux``
-* VyOS rolling release you should use ``vyos/vyos-build`` which will always
-  refer to the latest image.
 
 Customisation
 ^^^^^^^^^^^^^