Merge pull request #45 from chipspeak/GUIDEFRAME-58

task(GUIDEFRAME-58): extensive README update.

Author: chipspeak

README.md

@@ -1,18 +1,56 @@
 # GuideFrame
 
-A walkthrough video generation tool created for the final project module on the HDip in Computer Science SETU 
+GuideFrame is a tool which allows software developers to produce detailed walkthrough videos of their projects using python code. It can be run locally, provided you have the required packages installed, or can be used as a GitHub action.
+
+It uses a selection of open-source software to record a users screen, perform scripted UI interactions and generate a matching voiceover based on a user-defined markdown file.
 
 ## Installation
 
-GuideFrame is packaged and available on pypi. It can be installed using:
+GuideFrame is currently available on PyPi. It can be installed using:`pip install guideframe`.
+While GuideFrame can be run locally, given the variance in development environment, using it as part of a GitHub action is the recommended approach.
+
+More detailed installation instructions can be found on the official docs page [here](https://chipspeak.github.io/GuideFrame/installation/).
+
+## Getting Started
+
+If you simply want to get started, a template repository exists to enable users to dive in without the need to navigate local dependencies, python environments etc. Simply clone or fork the repository listed below to have access to a correctly configured template. You can then modify the GuideFrame script and markdown as needed for your purpose. Then you need only enable the GitHub action to begin your first render.
+
+[GuideFrame Template Repository](https://github.com/chipspeak/GuideFrame-Template)
+
+## Samples
+
+If you wish to view the syntax of GuideFrame through the lense of examples, see the below links.
+
+**Tutors Demo** - A brief GuideFrame walkthrough using [tutors.dev](tutors.dev)
+* [GuideFrame Tutors Demo script](https://github.com/chipspeak/GuideFrame/blob/main/guideframe_demos/tutors_demo/guideframe_tutors_demo.py)
+* [GuideFrame Tutors Demo markdown](https://github.com/chipspeak/GuideFrame/blob/main/guideframe_demos/tutors_demo/guideframe_tutors_demo.md)
+* [GuideFrame Tutors Demo video](https://www.youtube.com/watch?v=Hq5pKuotsac)
+
+**Magento Demo** - A GuideFrame selenium function demo using the [Magento test site](https://magento.softwaretestingboard.com/)
+* [GuideFrame Magento Demo script](https://github.com/chipspeak/GuideFrame/blob/main/selenium_demos/selenium_function_demo.py)
+* [GuideFrame Magento Demo markdown](https://github.com/chipspeak/GuideFrame/blob/main/selenium_demos/selenium_function_demo.md)
+* [GuideFrame Magento Demo video](https://www.youtube.com/watch?v=O9Mt2SXts-0)
+
+**GuideFrame Code Walkthrough** - An elaborate GuideFrame walkthrough where it works through its own code.
+* [GuideFrame Code Walkthrough script](https://github.com/chipspeak/GuideFrame/blob/main/guideframe_demos/guideframe_code_demo/guideframe_code_demo.py)
+* [GuideFrame Code Walkthrough mardkwon](https://github.com/chipspeak/GuideFrame/blob/main/guideframe_demos/guideframe_code_demo/guideframe_code_demo.md)
+* [GuideFrame Code Walkthrough video](https://www.youtube.com/watch?v=EZVsS7ulclA)
+
+## Additional Links
+* [GuideFrame On PyPi](https://pypi.org/project/guideframe/)
+* [GuideFrame Official Docs](https://chipspeak.github.io/GuideFrame/)
+
+## Technologies Used
+* [`ffmpeg`](https://www.ffmpeg.org/) - used to capture the virtual displays and combine clips.
+* [`gTTS`](https://pypi.org/project/gTTS/) - used to generate the voiceover audio.
+* [`xvfb`](https://linux.die.net/man/1/xvfb) - used to provide a virtual display server.
+* [`mutagen`](https://mutagen.readthedocs.io/en/latest/index.html) - used to parse MP3 length.
+* [`chromium`](https://www.chromium.org/Home/) - to provide a browser for interactions.
+* [`selenium`](https://pypi.org/project/selenium/) - the python package for interacting with the browser.
 
-```pip install guideframe```
+## How To Contribute
+GuideFrame is an open-source project and contributions are greatly encouraged. Open an issue thread or fork the repo and open a pull request if you've got suggestions, fixes etc. 
 
-Once installed, you will need to install the non-python dependencies. A setup script is packaged with GuideFrame for this. You can simply copy it from the GuideFrame repo and run it locally or you can run the following:
 
-```bash $(python -c "import guideframe, os; print(os.path.join(os.path.dirname(guideframe.__file__), 'setup_env.sh'))")```
 
-In aid of illustrating the basics of GuideFrame, a template repository has been created and can be found here:
-https://github.com/chipspeak/GuideFrame-Template
 
-This repository walks a user through the installation process in addition to providing some basics around the workings of GuideFrame in addition to some basic templates.