Updated readme with modern guidelines on how to build docs

README.md

@@ -1,28 +1,47 @@
 Documentation
 =============
-This is the documentation for the [MATLAB](https://github.com/RascalSoftware/RAT) and [Python](https://github.com/RascalSoftware/python-RAT) versions of the RAT project. 
+This is the documentation for the [MATLAB](https://github.com/RascalSoftware/RAT) and [Python](https://github.com/RascalSoftware/python-RAT) versions of the RAT project. The installation instruction provided in assumption that you are using [conda](https://docs.conda.io/) for managing your python packages.
 
 Build docs
 ----------
 The documentation should be built using the provided Sphinx make file. The reStructuredText source is in the source 
 folder while the build will be placed in a build folder. The build requires a python executable and the python packages 
-in the requirements.txt. 
+in the requirements.txt. You need MATLAB version and python version or RAT software installed in your system.
 
-    conda create -n RAT python=3.9
-    conda activate RAT
-    pip install -r requirements.txt
+    >>conda create -n RAT python=3.9
+    >>conda activate RAT
+    >>pip install -r requirements.txt
 
-Download the appropriate version of RAT from the GitHub [release](https://github.com/RascalSoftware/RAT/releases) page, and unzip the contents into a folder called API (This folder should be in the root directory). For example on a Linux machine, the nightly can be downloaded as shown 
+You also must have `pandoc` installed to build the Python example Jupyter notebooks. See the installation instructions [here](https://pandoc.org/installing.html). If not previously installed system-wide, install [pandoc](https://pandoc.org/) using conda:
 
-    wget https://github.com/RascalSoftware/RAT/releases/download/nightly/Linux.zip
-    unzip Linux.zip -d API/
+    >>conda install -c conda-forge pandoc
+    or
+    >>pixi global install pandoc
+    or
+    >>micromamba install pandoc 
 
-You also must have `pandoc` installed to build the Python example Jupyter notebooks. See the installation instructions [here](https://pandoc.org/installing.html).
+depending on [conda](https://docs.conda.io/) flavour you are using.
 
+If not installed before, download the appropriate version of RAT from the GitHub [release](https://github.com/RascalSoftware/RAT/releases) page, and unzip the contents into a folder called API (This folder should be located within python-RAT directory, alongside main `.github` folder). For example on a Linux machine, the nightly can be downloaded as shown:
+
+    >>wget https://github.com/RascalSoftware/RAT/releases/download/nightly/Linux.zip
+    >>unzip Linux.zip -d API/
+
+If RAT is installed, you may create symbolic link to the existing installation directory. E.g.,
+if  MATLAB RAT software is installed in `[Users,home]/myUsername/RAT` folder and RAT documentation repository is cloned into `[Users,home]/myUsername/RAT-doc`, run:
+
+    for Windows:
+    >>cd c:\users\myUsername\Rat-doc
+    >>mklink /j API c:\Users\myUsername\RAT 
+    for linux/macOS;
+    >>cd /home/myUsername/RAT-doc
+    >>ln -s /home/myUsername/RAT  API
+
+You also need [Python RAT API](https://github.com/RascalSoftware/python-RAT) to be build and available for your local RAT `conda` session. Build process will add modules necessary for generating python documentation to the python modules search path. Look at [Python RAT repository](https://github.com/RascalSoftware/python-RAT/blob/main/README.md) for more information how to build python API.
 
 To build the HTML docs, type the following into a terminal with access to the Python executable:  
 
-    make html
+    >>make html
 
 [`matlabengine`](https://pypi.org/project/matlabengine/) is required to generate MATLAB code snippet outputs. If `matlabengine` is not installed, the outputs will be omitted and the following warning will be printed in the terminal: