From 7c3d0f829492cf529797dda9bf3c42f13f14672b Mon Sep 17 00:00:00 2001 From: abuts Date: Wed, 6 Aug 2025 12:41:31 +0100 Subject: [PATCH 01/11] Re #50 Updated readme with modern guidelines on how to build docs --- README.md | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index c8fe400a..24556a86 100644 --- a/README.md +++ b/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]/myFedID/RAT` folder, run: + + for Windows: + >>cd c:\users\myFedID\Rat-doc + >>mklink /j API c:\Users\myFedID\RAT + for linux/macOS; + >>cd /home/myFedID/RAT-doc + >>ln -s /home/myFedID/RAT API + +You also need [Python RAT API](https://github.com/RascalSoftware/python-RAT) to be build and available in your local RAT `conda` session. Look [there](https://github.com/RascalSoftware/python-RAT/blob/main/README.md) on 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: From 5fd3bf76ae176597696e7880ac850943ab4f6a2e Mon Sep 17 00:00:00 2001 From: abuts Date: Thu, 7 Aug 2025 10:27:51 +0100 Subject: [PATCH 02/11] Re #50 minor comment on what RAT-python builds process does --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 24556a86..fc2a6aec 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ if MATLAB RAT software is installed in `[Users,home]/myFedID/RAT` folder, run: >>cd /home/myFedID/RAT-doc >>ln -s /home/myFedID/RAT API -You also need [Python RAT API](https://github.com/RascalSoftware/python-RAT) to be build and available in your local RAT `conda` session. Look [there](https://github.com/RascalSoftware/python-RAT/blob/main/README.md) on more information how to build python API. +You also need [Python RAT API](https://github.com/RascalSoftware/python-RAT) to be build and available in your local RAT `conda` session. This will add modules necessary for generate python documentation to the python modules search path. Look [there](https://github.com/RascalSoftware/python-RAT/blob/main/README.md) on more information how to build python API. To build the HTML docs, type the following into a terminal with access to the Python executable: From 710c56b766afc0ab816ac92e6d19dc80e3757f7f Mon Sep 17 00:00:00 2001 From: abuts Date: Thu, 7 Aug 2025 10:31:54 +0100 Subject: [PATCH 03/11] Re #50 minor -- thought about build reformulated --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fc2a6aec..a292a002 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ if MATLAB RAT software is installed in `[Users,home]/myFedID/RAT` folder, run: >>cd /home/myFedID/RAT-doc >>ln -s /home/myFedID/RAT API -You also need [Python RAT API](https://github.com/RascalSoftware/python-RAT) to be build and available in your local RAT `conda` session. This will add modules necessary for generate python documentation to the python modules search path. Look [there](https://github.com/RascalSoftware/python-RAT/blob/main/README.md) on more information how to build python API. +You also need [Python RAT API](https://github.com/RascalSoftware/python-RAT) to be build and available in your local RAT `conda` session. Build process will add modules necessary for generate python documentation to the python modules search path. Look [there](https://github.com/RascalSoftware/python-RAT/blob/main/README.md) on more information how to build python API. To build the HTML docs, type the following into a terminal with access to the Python executable: From 7dfdddb2838e44452407489e9e1027547a5f4146 Mon Sep 17 00:00:00 2001 From: abuts Date: Thu, 7 Aug 2025 19:32:51 +0100 Subject: [PATCH 04/11] Re #50 Minor typo and syntax in README.md --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a292a002..295281af 100644 --- a/README.md +++ b/README.md @@ -28,16 +28,16 @@ If not installed before, download the appropriate version of RAT from the GitHub >>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]/myFedID/RAT` folder, run: +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\myFedID\Rat-doc - >>mklink /j API c:\Users\myFedID\RAT + >>cd c:\users\myUsername\Rat-doc + >>mklink /j API c:\Users\myUsername\RAT for linux/macOS; - >>cd /home/myFedID/RAT-doc - >>ln -s /home/myFedID/RAT API + >>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 in your local RAT `conda` session. Build process will add modules necessary for generate python documentation to the python modules search path. Look [there](https://github.com/RascalSoftware/python-RAT/blob/main/README.md) on more information how to build python 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: From 8e706fecd3fd6b8e7b583aee3aa4538a8b9f0db8 Mon Sep 17 00:00:00 2001 From: abuts Date: Tue, 12 Aug 2025 18:02:28 +0100 Subject: [PATCH 05/11] Re #50 changes from review. --- README.md | 49 ++++++++++++++++++++++++------------------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 295281af..87a47ca1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ 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. The installation instruction provided in assumption that you are using [conda](https://docs.conda.io/) for managing your python packages. +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 here, assumes [conda](https://docs.conda.io/) is used to manage python packages, please adapt as needed for a different package manager. Build docs ---------- @@ -8,40 +8,39 @@ The documentation should be built using the provided Sphinx make file. The reStr 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. 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 - -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: - - >>conda install -c conda-forge pandoc - or - >>pixi global install pandoc - or - >>micromamba install pandoc +```bash + conda create -n RAT python=3.9 + conda activate RAT + pip install -r requirements.txt +``` +You also must have `pandoc` installed to build the Python example Jupiter notebooks. See the installation instructions [here](https://pandoc.org/installing.html). If not previously installed system-wide, install [pandoc](https://pandoc.org/) using [conda](https://docs.conda.io/) as described in their [installation manual](https://pandoc.org/installing.html#conda-forge) 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: +If you do not have RAT code on your machine, 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/ +```bash + 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: +If RAT is already present, you may create symbolic link to the existing` RAT` directory. E.g.: + +for Windows: + cd path_to_rat_docs_folder + mklink /j API paht_to_matlap_rat_folder + +for linux/macOS: + cd path_to_rat_docs_folder + ln -s /home/myUsername/RAT API - 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 +Where `path_to_rat_docs_folder` is the path to the RAT documentation repository and `paht_to_matlap_rat_folder` is the path to the downloaded MATLAB RAT release -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. +[Python RAT API](https://github.com/RascalSoftware/python-RAT) should be installed on the same python virtual environment created earlier. Build process adds 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 on 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: From bb032af833acc455f0ab074bd507d59c8ff05091 Mon Sep 17 00:00:00 2001 From: abuts Date: Tue, 12 Aug 2025 18:07:38 +0100 Subject: [PATCH 06/11] Re #50 change python-RAT to RAT-doc --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 87a47ca1..748eb991 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ in the requirements.txt. You need MATLAB version and python version or RAT softw You also must have `pandoc` installed to build the Python example Jupiter notebooks. See the installation instructions [here](https://pandoc.org/installing.html). If not previously installed system-wide, install [pandoc](https://pandoc.org/) using [conda](https://docs.conda.io/) as described in their [installation manual](https://pandoc.org/installing.html#conda-forge) depending on [conda](https://docs.conda.io/) flavour you are using. -If you do not have RAT code on your machine, 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: +If you do not have RAT code on your machine, 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 RAT-doc directory, alongside main `.github` folder). For example on a Linux machine, the nightly can be downloaded as shown: ```bash wget https://github.com/RascalSoftware/RAT/releases/download/nightly/Linux.zip From 0d650acf919b567bdd0ba0ac78052185e3471e27 Mon Sep 17 00:00:00 2001 From: abuts Date: Tue, 12 Aug 2025 18:09:00 +0100 Subject: [PATCH 07/11] Re #50 small typo with e.g. not noticed before --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 748eb991..32bbe38a 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ If you do not have RAT code on your machine, download the appropriate version of unzip Linux.zip -d API/ ``` -If RAT is already present, you may create symbolic link to the existing` RAT` directory. E.g.: +If RAT is already present, you may create symbolic link to the existing` RAT` directory, e.g.: for Windows: cd path_to_rat_docs_folder From bdae54227179a533ba80c89fa8ba2d797f2b1850 Mon Sep 17 00:00:00 2001 From: abuts Date: Tue, 12 Aug 2025 18:10:24 +0100 Subject: [PATCH 08/11] Re #50 typo in code blocks --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 32bbe38a..03798b3e 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,12 @@ If you do not have RAT code on your machine, download the appropriate version of If RAT is already present, you may create symbolic link to the existing` RAT` directory, e.g.: for Windows: + cd path_to_rat_docs_folder mklink /j API paht_to_matlap_rat_folder for linux/macOS: + cd path_to_rat_docs_folder ln -s /home/myUsername/RAT API From c66c25786bfd3571d5ecea79acffe6d02f959760 Mon Sep 17 00:00:00 2001 From: abuts Date: Tue, 12 Aug 2025 18:41:58 +0100 Subject: [PATCH 09/11] Re #50 minor typos --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 03798b3e..9b0aaf79 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,16 @@ If RAT is already present, you may create symbolic link to the existing` RAT` di for Windows: cd path_to_rat_docs_folder - mklink /j API paht_to_matlap_rat_folder + mklink /j API path_to_matlap_rat_folder for linux/macOS: +```bash cd path_to_rat_docs_folder - ln -s /home/myUsername/RAT API + ln -s path_to_matlap_rat_folder API +``` -Where `path_to_rat_docs_folder` is the path to the RAT documentation repository and `paht_to_matlap_rat_folder` is the path to the downloaded MATLAB RAT release +Where `path_to_rat_docs_folder` is the path to the RAT documentation repository and `path_to_matlap_rat_folder` is the path to the downloaded MATLAB RAT release [Python RAT API](https://github.com/RascalSoftware/python-RAT) should be installed on the same python virtual environment created earlier. Build process adds 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 on how to build python API. From e1d933f86d98a2427e7e4cbefc0e527f1e60c64a Mon Sep 17 00:00:00 2001 From: abuts Date: Wed, 13 Aug 2025 19:32:25 +0100 Subject: [PATCH 10/11] Re #50 minor changes from review and typos --- README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 9b0aaf79..47b24907 100644 --- a/README.md +++ b/README.md @@ -9,36 +9,38 @@ folder while the build will be placed in a build folder. The build requires a py in the requirements.txt. You need MATLAB version and python version or RAT software installed in your system. ```bash - 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 ``` You also must have `pandoc` installed to build the Python example Jupiter notebooks. See the installation instructions [here](https://pandoc.org/installing.html). If not previously installed system-wide, install [pandoc](https://pandoc.org/) using [conda](https://docs.conda.io/) as described in their [installation manual](https://pandoc.org/installing.html#conda-forge) depending on [conda](https://docs.conda.io/) flavour you are using. -If you do not have RAT code on your machine, 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 RAT-doc directory, alongside main `.github` folder). For example on a Linux machine, the nightly can be downloaded as shown: +If you do not have RAT code on your machine, 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 RAT-doc directory, alongside the **source** folder and main `make.bat` file (see below)). For example on a Linux machine, the nightly can be downloaded as shown: ```bash + cd path_to_rat_docs_folder wget https://github.com/RascalSoftware/RAT/releases/download/nightly/Linux.zip unzip Linux.zip -d API/ ``` +Where `path_to_rat_docs_folder` is the location where documentation is cloned or unpacked. If RAT is already present, you may create symbolic link to the existing` RAT` directory, e.g.: for Windows: cd path_to_rat_docs_folder - mklink /j API path_to_matlap_rat_folder + mklink /j API path_to_matlab_rat_folder for linux/macOS: ```bash - cd path_to_rat_docs_folder - ln -s path_to_matlap_rat_folder API + cd path_to_rat_docs_folder + ln -s path_to_matlab_rat_folder API ``` -Where `path_to_rat_docs_folder` is the path to the RAT documentation repository and `path_to_matlap_rat_folder` is the path to the downloaded MATLAB RAT release +Where `path_to_rat_docs_folder` is the path to the RAT documentation repository and `path_to_matlab_rat_folder` is the path to the downloaded MATLAB RAT release [Python RAT API](https://github.com/RascalSoftware/python-RAT) should be installed on the same python virtual environment created earlier. Build process adds 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 on how to build python API. From 58f1213f322d9ac3fa906f04af6502f24a9fd183 Mon Sep 17 00:00:00 2001 From: abuts Date: Wed, 13 Aug 2025 19:35:40 +0100 Subject: [PATCH 11/11] Re #50 minor typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 47b24907..ae07b5a0 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ in the requirements.txt. You need MATLAB version and python version or RAT softw You also must have `pandoc` installed to build the Python example Jupiter notebooks. See the installation instructions [here](https://pandoc.org/installing.html). If not previously installed system-wide, install [pandoc](https://pandoc.org/) using [conda](https://docs.conda.io/) as described in their [installation manual](https://pandoc.org/installing.html#conda-forge) depending on [conda](https://docs.conda.io/) flavour you are using. -If you do not have RAT code on your machine, 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 RAT-doc directory, alongside the **source** folder and main `make.bat` file (see below)). For example on a Linux machine, the nightly can be downloaded as shown: +If you do not have RAT code on your machine, 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 RAT-documentation directory, alongside the **source** folder and main `make.bat` file (see below)). For example on a Linux machine, the nightly can be downloaded as shown: ```bash cd path_to_rat_docs_folder