update readthedocs config and add installation docs (#3436)

- update readthedocs config to support copy action in command palette.
- add installation guide for pbench-agent via rpm, ansible and
  containers.
- mapped end-to-end workflow page to index.rst
- update docs/readme

Demo [link](https://pb-readthedocs.readthedocs.io/en/latest/Agent/installation/index.html)

* resolve review comments

* resolve ansible and rpm install doc review comments

* Resolve webbs review comments

* Resolve review comments

docs/Agent/installation/ansible_based_installation.md

@@ -0,0 +1,37 @@
+# Ansible based installation
+
+In the following: we describe how to install Pbench Agent using an ANSIBLE playbook.
+
+:::{note}
+The same Pbench Agent version must be installed on all the test systems that participate in a benchmark run, there is no support for mixed installations.
+:::
+
+## Setup
+
+1. Make sure that you have the ANSIBLE package installed.
+
+2. Install the `pbench.agent` ANSIBLE collection from Ansible Galaxy.
+
+ ```console
+ ansible-galaxy collection install pbench.agent
+ ```
+
+3. Tell ansible where to find these roles.
+
+ ```console
+ export ANSIBLE_ROLES_PATH=$HOME/.ansible/collections/ansible_collections/pbench/agent/roles:$ANSIBLE_ROLES_PATH
+ ```
+
+4. Create an inventory file (`~/.config/Inventory/myhosts.inv`) naming the hosts on which you wish to install Pbench Agent and the location of the config file. Example [inventory file](assets/myhosts.inv).
+
+:::{note}
+if you're planning to push performance data to a 0.69 Pbench Server, you need to specify the server's private RSA key. Example [inventory file](assets/0.69_myhosts.inv).
+:::
+
+5. Use the [example playbook](https://github.com/distributed-system-analysis/pbench/blob/main/agent/ansible/playbooks/pbench_agent_install.yml) or reference it to customize your own.
+
+6. Run the playbook.
+
+ ```console
+ ansible-playbook -i ~/.config/Inventory/myhosts.inv pbench_agent_install.yml
+ ```

docs/Agent/installation/assets/0.69_myhosts.inv

@@ -0,0 +1,11 @@
+[servers]
+<host1>
+<host2>
+<host3>
+
+[servers:vars]
+# where to get the key
+pbench_key_url = <url>
+
+# where to get the config file
+pbench_config_url = <url>

docs/Agent/installation/assets/myhosts.inv

@@ -0,0 +1,8 @@
+[servers]
+<host1>
+<host2>
+<host3>
+
+[servers:vars]
+# where to get the config file
+pbench_config_url = <url>

docs/Agent/installation/index.rst

@@ -8,5 +8,5 @@ Choose any one of the following approaches to setup `Pbench Agent`
 
    pbench-containers
    rpm_based_installation
-   Ansible_based_installation
+   ansible_based_installation
 

docs/Agent/installation/pbench-containers.md

@@ -1,2 +1,23 @@
-# Pbench containers
-
+# Pbench Agent Container
+
+Pbench Agent is available as container images on [Quay.io](https://quay.io/organization/pbench). This makes Pbench Agent a distro-independent solution and it could also be used in any containerized ecosystem.
+
+**Want to build container images from sources?**  
+Follow [README](https://github.com/distributed-system-analysis/pbench/blob/main/agent/containers/images/README.md)
+
+Running Pbench Agent container is as simple as  
+```console
+podman run quay.io/pbench/pbench-agent-all-centos-8
+```  
+Depending on the use cases one has to run these containers with privileged mode, host network, pid, ipc, mount required volumes, etc.
+
+Example:
+```console
+podman run --name pbench --rm -ti --privileged --ipc=host --net=host --pid=host -e HOST=/host -e NAME=pbench -e IMAGE=quay.io/pbench/pbench-agent-all-centos-8 -v /run:/run -v /var/log:/var/log -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -v /:/host quay.io/pbench/pbench-agent-all-centos-8
+```
+
+:::{note}
+The volumes and config shown in the command snippet above may vary depending on users needs.
+:::
+
+Possibilities are endless, please give it a try <https://quay.io/organization/pbench>.

docs/Agent/installation/rpm_based_installation.md

@@ -1 +1,43 @@
 # RPM based installation
+
+The Pbench Agent requires the installation of some generic bits, but it also
+requires some localization. It needs to know where to send the results for
+storage and analysis, and it needs to be able to authenticate to the results
+server.
+
+The generic bits are packaged as an RPM, available from
+[COPR](https://copr.fedorainfracloud.org/coprs/ndokos).
+Pbench Agent is built for all major releases of
+Fedora, RHEL, CentOS and openSUSE.
+
+In the following, we describe how to install Pbench Agent using an RPM.
+
+## Setup
+
+1. Enable required repos.
+
+	```console
+	dnf copr enable ndokos/pbench-0.72
+	dnf copr enable ndokos/pbench
+	```
+
+    :::{note}
+	- We release Pbench Agent RPMs under the `ndokos` COPR account with repos following the pattern `pbench-<release>`.
+	- There are some RPMs that are shared between versions (e.g. pbench-sysstat). We maintain those in [ndokos/pbench](https://copr.fedorainfracloud.org/coprs/ndokos/pbench) repo.
+    - On a RHEL-based system enable the subscription manager and enable the `EPEL` repo.
+	:::
+
+2. Install Pbench Agent package
+
+	```console
+	dnf install pbench-agent
+	```
+
+3. Restart terminal/shell session so that all environment varibales and PATH variables are updated
+
+	or 
+
+	```console
+	source /etc/profile.d/pbench-agent.sh
+	```
+

docs/Agent/user-guide/index.rst

@@ -6,4 +6,5 @@ User Guide
 
    getting_started
    UserGuide
-   man_page
+   man_page
+   guides/end-to-end-workflow

docs/README.md

@@ -8,7 +8,15 @@ Pbench website is hosted on gh-pages and readthedocs pages(`/docs`) are also hos
 
 ## Readthedocs setup
 
-`$ pip3 install -r requirement.txt`
-`$ make clean`
-`$ make html`
-> **Note:**  Above command will build your readthedocs page in `_build/html` dir.
+```console
+$ pip3 install -r requirements.txt
+$ make clean
+$ make html
+```
+
+> **Note:**  Above command will build your static readthedocs page/website in `_build/html` dir.
+
+## Some important links
+
+- [online markdown editor](https://pandao.github.io/editor.md/en.html)
+- [myst-parser](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) is a plugin used to build our markdown documentation.

docs/conf.py

@@ -43,6 +43,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx_design",
     "myst_parser",
+    "sphinx_copybutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/requirements.txt

@@ -1,3 +1,5 @@
-sphinx-design
+myst-parser
+sphinx-copybutton
 sphinx-rtd-theme
-myst-parser
+sphinx-design
+