Improve documentation

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,75 @@
+---
+name: Bug report
+about: "Report a bug or unexpected behavior when running ICortex"
+title: ''
+labels: bug
+assignees: osolmaz
+
+---
+
+<!-- Fill in the details below where applicable: -->
+
+## Description of bug / unexpected behavior
+<!-- Add a clear and concise description of the problem you encountered. -->
+
+
+## Expected behavior
+<!-- Add a clear and concise description of what you expected to happen. -->
+
+
+## How to reproduce the issue
+<!-- Provide a piece of code illustrating the undesired behavior. -->
+
+<details><summary>Code for reproducing the problem</summary>
+
+```py
+Paste your code here.
+```
+
+</details>
+
+
+## Additional media files
+<!-- Paste in the files manim produced on rendering the code above. -->
+
+<details><summary>Images/GIFs</summary>
+
+<!-- PASTE MEDIA HERE -->
+
+</details>
+
+
+## Logs
+<details><summary>Terminal output</summary>
+<!-- Add "-v DEBUG" when calling manim to generate more detailed logs -->
+
+```
+PASTE HERE OR PROVIDE LINK TO https://pastebin.com/ OR SIMILAR
+```
+
+<!-- Insert screenshots here (only when absolutely necessary, we prefer copy/pasted output!) -->
+
+</details>
+
+
+## System specifications
+
+<details><summary>System Details</summary>
+
+
+- OS (with version, e.g., Windows 10 v2004 or macOS 10.15 (Catalina)):
+- RAM:
+- Python version (run `python/py/python3 --version`):
+- ICortex version (run `pip show icortex | grep -i version`):
+- Other relevant modules (provide output from `pip list`):
+- Versions of Jupyter related packages (run `jupyter --version`):
+
+```
+PASTE HERE
+```
+</details>
+
+</details>
+
+## Additional comments
+<!-- Add further context that you think might be relevant for this issue here. -->

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Request a new feature for ICortex
+title: ""
+labels: enhancement
+assignees: 'osolmaz'
+
+---
+
+## Description of proposed feature
+<!-- Add a clear and concise description of the new feature, including a motivation: why do you think this will be useful? -->
+
+
+## How can the new feature be used?
+<!-- If possible, illustrate how this new feature could be used. -->
+
+
+## Additional comments
+<!-- Add further context that you think might be relevant. -->

.github/ISSUE_TEMPLATE/installation-issue.md

@@ -0,0 +1,49 @@
+---
+name: "Installation issue"
+about: "Report issues with the installation process of manim-voiceover"
+title: ''
+labels: installation
+assignees: osolmaz
+
+---
+
+#### Preliminaries
+
+- [ ] I have followed the latest version of the
+      [installation instructions](https://github.com/textcortex/icortex/blob/main/README.md).
+
+## Description of error
+<!-- Add a clear and concise description of the problem you encountered. -->
+
+
+## Installation logs
+<!-- Please paste the **full** terminal output; we can only help to identify the issue
+     when we receive all required information. -->
+
+<details><summary>Terminal output</summary>
+
+```
+PASTE HERE OR PROVIDE LINK TO https://pastebin.com/ OR SIMILAR
+```
+
+<!-- Insert screenshots here (only when absolutely necessary, we prefer copy/pasted output!) -->
+
+</details>
+
+
+## System specifications
+
+<details><summary>System Details</summary>
+
+- OS (with version, e.g., Windows 10 v2004 or macOS 10.15 (Catalina)):
+- RAM:
+- Python version (`python/py/python3 --version`):
+- Installed modules (provide output from `pip list`):
+```
+PASTE HERE
+```
+</details>
+
+
+## Additional comments
+<!-- Add further context that you think might be relevant for this issue here. -->

.readthedocs.yml

@@ -0,0 +1,11 @@
+version: 2
+build:
+  image: latest
+sphinx:
+   configuration: docs/source/conf.py
+python:
+   version: 3.8
+   install:
+      - requirements: docs/requirements.txt
+      - method: pip
+        path: .

README.md

@@ -1,126 +1,67 @@
-# ICortex Kernel
-
-![Github Actions Status](https://github.com/textcortex/icortex/workflows/Build/badge.svg)
-[![License](https://img.shields.io/github/license/textcortex/icortex.svg?color=blue)](https://github.com/textcortex/icortex/blob/main/LICENSE)
-[![](https://dcbadge.vercel.app/api/server/QtfGgKneHX?style=flat)](https://discord.textcortex.com/)
-
-ICortex is a [Jupyter kernel](https://jupyter-client.readthedocs.io/en/latest/kernels.html) that lets you program using plain English, by generating Python code from natural language prompts:
+<p align="center">
+    <a href="https://icortex.ai/"><img src="https://raw.githubusercontent.com/textcortex/icortex/main/assets/logo/banner.svg"></a>
+    <br />
+    <br />
+    <a href="https://github.com/textcortex/icortex/workflows/Build/badge.svg"><img src="https://github.com/textcortex/icortex/workflows/Build/badge.svg" alt="Github Actions Status"></a>
+    <a href="https://pypi.org/project/icortex/"><img src="https://img.shields.io/pypi/v/icortex.svg?style=flat&logo=pypi" alt="PyPI Latest Release"></a>
+    <a href="https://pepy.tech/project/icortex"><img src="https://pepy.tech/badge/icortex/month?" alt="Downloads"> </a>
+    <a href="https://icortex.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/icortex/badge/?version=latest" alt="Documentation Status"></a>
+    <a href="https://github.com/textcortex/icortex/blob/main/LICENSE"><img src="https://img.shields.io/github/license/textcortex/icortex.svg?color=blue" alt="License"></a>
+    <a href="https://discord.textcortex.com/"><img src="https://dcbadge.vercel.app/api/server/QtfGgKneHX?style=flat" alt="Discord"></a>
+    <a href="https://twitter.com/TextCortex/"><img src="https://img.shields.io/twitter/url/https/twitter.com/cloudposse.svg?style=social&label=Follow%20%40TextCortex" alt="Twitter"></a>
+    <br />
+    <br />
+    <i>A Python library for <a href="https://en.wikipedia.org/wiki/Soft_computing">soft-code</a> development — program in plain English with AI code generation!</i>
+</p>
+<hr />
+
+ICortex is a [Jupyter kernel](https://jupyter-client.readthedocs.io/en/latest/kernels.html) that lets you develop **soft programs**:
+
+- sets of instructions (i.e. prompts) [written in natural language](https://en.wikipedia.org/wiki/Natural-language_programming) (such as English)
+- processed by language models that generate Python code
+- to perform useful work in various contexts
+- more flexibly than regular software.
+
+To put it simply—in goes English, out comes Python:
 
 https://user-images.githubusercontent.com/2453968/196814906-1a0de2a1-27a7-4aec-a960-0eb21fbe2879.mp4
 
 TODO: Prompts are given using the %prompt magic now, update the video accordingly
 
-It is ...
+ICortex is ...
 
 - a drop-in replacement for the IPython kernel. Prompts can be executed with the [magic commands](https://ipython.readthedocs.io/en/stable/interactive/magics.html) `%prompt` or `%p` for short.
-- an interface for [Natural Language Programming](https://en.wikipedia.org/wiki/Natural-language_programming) interface—prompts written in plain English automatically generate Python code which can then be executed globally.
 - interactive—install missing packages directly, decide whether to execute the generated code or not, and so on, directly in the Jupyter Notebook cell.
 - open source and fully extensible—if you think we are missing a model or an API, you can request it by creating an issue, or implement it yourself by subclassing `ServiceBase` under [`icortex/services`](icortex/services).
 
-ICortex is currently in alpha, so expect breaking changes. We are giving free credits to our first users—[join our Discord](https://discord.textcortex.com/) to help us shape this product.
-
-## Installation
-
-To install the ICortex Kernel, run the following in the main project directory:
-
-```sh
-pip install icortex
-```
-
-This will install the Python package and the `icortex` command line interface. You will need to run `icortex` once to install the kernel spec to Jupyter.
-
-## Using ICortex
-
-Before you can use ICortex in Jupyter, you need to configure it for your current project.
-
-If you are using the terminal:
-
-```bash
-icortex init
-```
-
-Alternatively, you can initialize directly in a Jupyter Notebook ([instructions on how to start JupyterLab](https://jupyterlab.readthedocs.io/en/stable/getting_started/starting.html)):
-
-```
-%icortex init
-```
-
-The shell will then instruct you step by step and create a configuration file `icortex.toml` in the current directory.
-
-### Choosing a code generation service
-
-ICortex supports different code generation services such as the TextCortex API, OpenAI Codex API, local HuggingFace transformers, and so on.
-
-To use the TextCortex code generation API,
-
-1. [sign up on the website](https://app.textcortex.com/user/signup),
-2. [generate an API key on the dashboard](https://app.textcortex.com/user/dashboard/settings/api-key),
-3. and proceed to configure `icortex` for your current project:
-
-[![asciicast](https://asciinema.org/a/sTU1EaGFfi3jdSV8Ih7vulsfT.svg)](https://asciinema.org/a/sTU1EaGFfi3jdSV8Ih7vulsfT)
-
-If you use up the starter credits and would like to continue testing out ICortex, [hit us up on our Discord on #icortex channel](https://discord.textcortex.com) and we will charge your account with more free credits.
+It is similar to [Github Copilot](https://github.com/features/copilot) but with certain differences that make it stand out:
 
-You can also try out different services e.g. OpenAI's Codex API, if you have access. You can also run code generation models from HuggingFace locally, which we have optimized to run on the CPU—though these produce lower quality outputs due to being smaller.
+| Feature | GitHub Copilot | ICortex |
+|---|:---:|:---:|
+| Generates code ... | In the text editor | In a [Jupyter kernel](https://docs.jupyter.org/en/latest/projects/kernels.html) (language backend that provides the execution environment) |
+| From ... | Existing code and comments | Plain English prompts |
+| Level of control over context used to generate code | Low | High |
+| Plain language instructions are ... | Just comments | Standalone programs |
+| The resulting program is ... | Static | Dynamic—adapts to the context it is executed in |
+| Can connect to different code generation APIs | No | Yes |
 
-## Usage
+The main difference between ICortex and a code-generation plugin like GitHub Copilot is that ICortex is a programming paradigm similar to [literate programming](https://en.wikipedia.org/wiki/Literate_programming) or [natural language programming](https://en.wikipedia.org/wiki/Natural-language_programming), where the natural language prompt is the first-class citizen, and which allows for fine-grained control over the code-generation context.
 
-### Executing prompts
+ICortex is currently in alpha, so expect breaking changes. We are giving free credits to our first users—[join our Discord](https://discord.textcortex.com/) to help us shape it.
 
-To execute a prompt with ICortex, use the `%prompt` [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html) (or `%p` for short) as a prefix. Copy and paste the following prompt into a cell and try to run it:
-
-```
-%p print Hello World. Then print the Fibonacci numbers till 100
-```
-
-Depending on the response, you should see an output similar to the following:
-
-```
-print('Hello World.', end=' ')
-a, b = 0, 1
-while b < 100:
-    print(b, end=' ')
-    a, b = b, a+b
-
-Hello World.
-1 1 2 3 5 8 13 21 34 55 89
-```
-
-You can also specify variables or options with command line flags, e.g. to auto-install packages, auto-execute the returned code and so on. To see the complete list of variables for your chosen service, run:
-
-```
-%help
-```
-
-### Using ICortex CLI
+## Installation
 
-ICortex comes with a full-fledged CLI similar to git or Docker CLI, which you can use to configure how you generate code in your project. To see all the commands you can invoke, run
+Install directly from PyPI:
 
 ```sh
-icortex help
-```
-
-For example the command `icortex service` lets you configure the code generation service you would like to use. To see how to use each command, call them with `help`
-
-```
-icortex service help
-```
-
-### Accessing ICortex CLI inside Jupyter
-
-You can still access the `icortex` CLI in a Jupyter Notebook or shell by using the magic command `%icortex`. For example running the following in the terminal switches to a local HuggingFace model:
-
-```
-icortex service set huggingface
+pip install icortex
+# This line is needed to install the kernel spec to Jupyter:
+python -m icortex.kernel.install
 ```
 
-To do the same in a Jupyter Notebook, you can run
-
-```
-%icortex service set huggingface
-```
+## Quickstart
 
-in a cell, which initializes and switches to the new service directly in your Jupyter session.
+[Click here to visit the docs and get started using ICortex](https://icortex.readthedocs.io/en/latest/quickstart.html).
 
 ## Getting help