docs

codegrits · Dec 26, 2023 · e08a57f · e08a57f
1 parent 2f974bf
commit e08a57f
Show file tree

Hide file tree

Showing 13 changed files with 202 additions and 85 deletions.
diff --git a/.idea/workspace.xml b/.idea/workspace.xml
diff --git a/README.md b/README.md
@@ -3,64 +3,24 @@
 ## What is CodeGRITS?
 
 CodeGRITS stands for **G**aze **R**ecording & **I**DE **T**racking **S**ystem, which is a plugin specifically designed
-for SE researchers. CodeGRITS is built on top of IntelliJ’s SDK, with wide compatibility with the
-entire family of JetBrains IDEs to track developers’ IDE interactions and eye gaze data.
+for empirical software engineering (SE) researchers. CodeGRITS is built on top of IntelliJ’s SDK, with wide
+compatibility with the entire family of JetBrains IDEs to track developers’ IDE interactions and eye gaze data.
+
+<div style="text-align: center;">
+    <img src="imgs/overview.png" style="width: 55%;">
+</div>
 
 ## Key Features
 
-- **Gaze and IDE Recording**: CodeGRITS records developers’ eye gaze data and
-  IDE interactions.
-- **Screen Recording**: CodeGRITS records developers’ screen.
-- **Research Toolkit**: CodeGRITS provides a set of extra features for SE
-  researchers, including preset labels, real-time data API, etc.
+- **Gaze and IDE Recording**: CodeGRITS tracks developers’ IDE interactions and eye gaze data for further understanding
+  their behaviors.
+- **Screen Recording**: CodeGRITS simultaneously records developers’ screen for visualizing their behaviors.
+- **Research Toolkit**: CodeGRITS provides a set of extra features for empirical SE
+  researchers, including dynamic configuration, activity labeling, etc.
 - **Data Export**: CodeGRITS exports data in XML format for further analysis.
 - **Real-time Data API**: CodeGRITS provides real-time data API for further
   development.
-
-## Using CodeGRITS
-
-### Python Environment
-
-It is necessary to install the following packages in your python environment to run this plugin.
-
-```
-python==3.8.8
-tobii-research==1.10.1
-pyautogui==0.9.53
-screeninfo==0.8
-```
-
-### Installation
-
-1. Clone the [repository](https://github.com/codegrits/CodeGRITS) to your local machine.
-2. Open command line and run `./gradlew build` in the root folder to build the plugin.
-3. Open IntelliJ IDEA and click `File` - `Settings` - `Plugins` - `Install Plugin from Disk...` to install the plugin
-   zip file in `build/distributions` folder.
-4. Restart IntelliJ IDEA to enable the plugin.
-5. All CodeGRITS features are available in `Tools` dropdown menu, including `Start Tracking`, `Pause Tracking`,
-   and `Configuration`.
-
-### Usage
-
-!!!
-Before starting tracking, you should first configure the plugin. Click `Tools` - `CodeGRITS` - `Configuration` to open
-the configuration window. To enable eye tracking,
-you need to have the necessary Python packages installed in your Python environment. The plugin automatically checks the
-Python environment.
-
-We highly recommend
-using [Tobii Pro Eye Tracker Manager](https://www.tobii.com/products/software/applications-and-developer-kits/tobii-pro-eye-tracker-manager#downloads)
-to conduct calibration before using eye tracking.
-!!!
-
-1. Click `Tools` - `CodeGRITS` - `Start Tracking` to start tracking.
-2. Click `Tools` - `CodeGRITS` - `Pause Tracking` to pause tracking.
-3. Click `Tools` - `CodeGRITS` - `Resume Tracking` to resume tracking.
-4. Click `Tools` - `CodeGRITS` - `Stop Tracking` to stop tracking. The plugin will export data in XML format to the
-   configured folder.
-
-## Further Development
-
-1. Click `Run` - `Run Plugin` to run the plugin and test it.
-2. Open command line and run `./gradlew build` to build the plugin.
-3. Get the plugin zip file in `build/distributions` folder.
+- **Cross-platform**: CodeGRITS provides cross-platform support for Windows, macOS,
+  and Linux, and is compatible with the entire family of JetBrains IDEs (e.g., IntelliJ IDEA, PyCharm, PhpStorm, etc.).
+- **Multilingual Support**: CodeGRITS could extract the abstract syntax tree (AST) structure of eye gazes on multiple
+  programming languages, including Java, Python, C/C++, JavaScript, etc.
diff --git a/API Reference.md → docs/api-reference.md b/API Reference.md → docs/api-reference.md
@@ -1,4 +1,9 @@
-# Real-time Data API Reference
+---
+icon: gear
+order: 70
+---
+
+# Real-time Data API
 
 ## Overview
 We provide a real-time data API for future plugin developers and researchers to get the real-time data from IDE tracker and eye tracker separately. The API is based on the [IDE Tracker](#ide-tracker) and [Eye Tracker](#eye-tracker).

diff --git a/docs/citation.md b/docs/citation.md
@@ -0,0 +1,31 @@
+---
+label: Citation & Demonstration
+icon: pencil
+order: 60
+---
+
+# Citation
+
+CodeGRITS has been accepted
+by [ICSE 2024 Demonstrations Track](https://conf.researchr.org/track/icse-2024/icse-2024-demonstrations).
+The PDF version of the paper is available [here](https://arxiv.org/abs/xxxx.yyyyy).
+Please cite the following paper if you use CodeGRITS in your research.
+
+```bibtex
+@inproceedings{tang2024codegrits,
+  title={CodeGRITS: A Research Toolkit for Developer Behavior and Eye Tracking in IDE},
+  author={Tang, Ningzhi and An, Junwen and Chen, Meng and Bansal, Aakash and Huang, Yu and McMillan, Collin and Li, Toby Jia-Jun},
+  booktitle={46th International Conference on Software Engineering Companion (ICSE-Companion '24)},
+  year={2024},
+  organization={ACM}
+}
+```
+
+# Demonstration
+
+We have also prepared a video demonstration of CodeGRITS for ICSE 2024.
+
+[!embed](https://www.youtube.com/embed/d-YsJfW2NMI)
+
+
+
diff --git a/docs/imgs/eye-tracking.png b/docs/imgs/eye-tracking.png
diff --git a/docs/imgs/ide-tracking.png b/docs/imgs/ide-tracking.png
diff --git a/logo.png → docs/imgs/logo.png b/logo.png → docs/imgs/logo.png
diff --git a/docs/imgs/overview.png b/docs/imgs/overview.png
diff --git a/docs/imgs/visualization.png b/docs/imgs/visualization.png
diff --git a/Output Format.md → docs/output.md b/Output Format.md → docs/output.md
@@ -1,3 +1,10 @@
+---
+id: Output Format
+icon: file-code
+order: 80
+---
+
+
 # Output Format
 
 ## Output Directory Structure

diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,66 @@
+---
+id: Usage Guide
+icon: book
+order: 90
+---
+
+# Usage Guide
+
+### Python Environment
+
+It is necessary to install the following packages in your python environment to run this plugin.
+
+```
+python==3.8.8
+tobii-research==1.10.1
+pyautogui==0.9.53
+screeninfo==0.8
+```
+
+### Installation
+
+1. Clone the [repository](https://github.com/codegrits/CodeGRITS) to your local machine.
+2. Open command line and run `./gradlew build` in the root folder to build the plugin.
+3. Open IntelliJ IDEA and click `File` - `Settings` - `Plugins` - `Install Plugin from Disk...` to install the plugin
+   zip file in `build/distributions` folder.
+4. Restart IntelliJ IDEA to enable the plugin.
+5. All CodeGRITS features are available in `Tools` dropdown menu, including `Start Tracking`, `Pause Tracking`,
+   and `Configuration`.
+
+### Usage
+
+!!!
+Before starting tracking, you should first configure the plugin. Click `Tools` - `CodeGRITS` - `Configuration` to open
+the configuration window. To enable eye tracking,
+you need to have the necessary Python packages installed in your Python environment. The plugin automatically checks the
+Python environment.
+
+We highly recommend
+using [Tobii Pro Eye Tracker Manager](https://www.tobii.com/products/software/applications-and-developer-kits/tobii-pro-eye-tracker-manager#downloads)
+to conduct calibration before using eye tracking.
+!!!
+
+1. Click `Tools` - `CodeGRITS` - `Start Tracking` to start tracking.
+2. Click `Tools` - `CodeGRITS` - `Pause Tracking` to pause tracking.
+3. Click `Tools` - `CodeGRITS` - `Resume Tracking` to resume tracking.
+4. Click `Tools` - `CodeGRITS` - `Stop Tracking` to stop tracking. The plugin will export data in XML format to the
+   configured folder.
+
+## Further Development
+
+1. Click `Run` - `Run Plugin` to run the plugin and test it.
+2. Open command line and run `./gradlew build` to build the plugin.
+3. Get the plugin zip file in `build/distributions` folder.
+
+## Example Output
+
+Here is one example of part of the output data, i.e., the IDE interactions and eye gaze data of a developer.
+[Output Format](Output%20Format.md) page provides a complete description of the output data.
+
+<div style="text-align: center;">
+    <img src="/docs/imgs/imgs/ide-tracking.png" style="width: 80%;"><br><br>
+    <img src="/docs/imgs/imgs/eye-tracking.png" style="width: 80%;"><br><br>
+</div>
+
+The source code of CodeGRITS is
+also publicly available on [GitHub](https://github.com/codegrits/CodeGRITS).
diff --git a/docs/welcome.md b/docs/welcome.md
@@ -0,0 +1,35 @@
+---
+label: Welcome
+icon: home
+order: 100
+---
+
+# Welcome to CodeGRITS
+
+CodeGRITS stands for **G**aze **R**ecording & **I**DE **T**racking **S**ystem, which is a plugin specifically designed
+for empirical software engineering (SE) researchers. CodeGRITS is built on top of IntelliJ’s SDK, with wide
+compatibility with the entire family of JetBrains IDEs to track developers’ IDE interactions and eye gaze data.
+
+<div style="text-align: center;">
+    <img src="imgs/overview.png" style="width: 55%;">
+</div>
+
+## Key Features
+
+- **Gaze and IDE Recording**: CodeGRITS tracks developers’ IDE interactions and eye gaze data for further understanding
+  their behaviors.
+- **Screen Recording**: CodeGRITS simultaneously records developers’ screen for visualizing their behaviors.
+- **Research Toolkit**: CodeGRITS provides a set of extra features for empirical SE
+  researchers, including dynamic configuration, activity labeling, etc.
+- **Data Export**: CodeGRITS exports data in XML format for further analysis.
+- **Real-time Data API**: CodeGRITS provides real-time data API for further
+  development.
+- **Cross-platform**: CodeGRITS provides cross-platform support for Windows, macOS,
+  and Linux, and is compatible with the entire family of JetBrains IDEs (e.g., IntelliJ IDEA, PyCharm, PhpStorm, etc.).
+- **Multilingual Support**: CodeGRITS could extract the abstract syntax tree (AST) structure of eye gazes on multiple
+  programming languages, including Java, Python, C/C++, JavaScript, etc.
+
+<div style="text-align: center;">
+    <img src="imgs/visualization.png" style="width: 80%;"><br><br>
+</div>
+
diff --git a/retype.yml b/retype.yml
@@ -1,10 +1,9 @@
-input: .
+input: ./docs
 output: .retype
 url:
 branding:
   title: CodeGRITS
-#  label: Docs
-  logo: /src/resources/pluginIcon.svg
+  logo: imgs/logo.png
 
 footer:
   copyright: "&copy; Copyright {{ year }}. All rights reserved."