Merge pull request #1 from Granite-Code/first-content

Add initial batch of content

Author: allanday

README.md

@@ -1,4 +1,11 @@
 # Granite.Code Docs
 
-Granite.code user documentation website. Content is written in Markdown. Static HTML site is generated using Sphinx.
+Granite.Code user documentation website. Content is written in Markdown. Static HTML site is generated using Sphinx.
 
+## Building
+
+To build this site locally, run:
+
+```
+sphinx-build -j auto -b html docs build
+```

docs/best-practices.md

@@ -0,0 +1,72 @@
+# Best Practices
+
+This page provides information on how to get the most out of Granite.Code. It covers best practices for getting accurate and helpful chat responses, as well as supplementary options which make Granite.Code's features even more powerful.
+
+Before you read this guide, you should be familiar with the main Granite.Code features, which are described in the [getting started tutorial](FIXME).
+
+## Asking effective questions
+
+Being able to chat with a local AI model is one of the main features offered by Granite.Code. When asking questions or creating prompts for an AI model, there are a number of best practices which will help you to get the best responses possible:
+
+* Always be as specific and precise as possible, and avoid broad or vague questions.
+* If you are asking a complex question, consider breaking it down into sections. Questions can include paragraphs and lists of information, which can be useful to keep them organized. This will make it easier for the model to interpret what you are asking.
+* If you want the model to provide an answer in a specific format, say what it is. For example, you could ask for a list of short points, or a code example, or you could ask for references for further reading.
+* If a question doesn't give you the answer you want, use follow-up questions to refine or amend it.
+
+Remember that asking AI models questions is a skill that gets better with practice.
+
+## Providing context for queries
+
+Most questions have a context that they are related to. In the coding world that context can be a project, a file, a programming language, a platform, or code section. However, by default an AI model has no information about that context: its response will be based only on the prompt it receives and the general information that it already has access to.
+
+This is where context comes in. Context allows you to feed additional information to the model, so that it has additional knowledge about the question you are asking. Granite.Code allows a variety of different types of context to be specified for a question. These include:
+
+* `@Files`: adds specific files
+* `@Folder`: adds a specific folder
+* `@Codebase`: adds all the files in the current project
+* `@Terminal`: adds the contents of the VS Code terminal
+* `@Git Diff`: adds the Git changes in the current branch
+* `@Problems`: adds data from the VS Code problems panel
+
+To use any of these types of context to a question, just type an **@** symbol in the chat, and a list of available context types will be shown. You can also click the **@** button in the chat prompt.
+
+Some examples of questions you can ask that make use of additional context:
+
+* Please summarize @sort.js
+* How do I fix the syntax errors in @sort.js @Problems
+* When I ran ``git pull`` I got weird errors. Please explain @Terminal
+* Please write a commit message for the current @Git Diff
+
+## Using docs
+
+`@Docs` is another powerful type of context in Granite.Code, which can be used to ask questions that have a documentation website as its context.
+
+What makes `@Docs` a little different is that it must be set up prior to use. To do this:
+
+1. Click the docs button above the chat prompt.
+2. Enter a title and URL for the docs site you want to make available.
+3. Click add, and wait for indexing to complete.
+
+Once this has been done you can enter `@Docs` in the chat prompt to use a docs site in a question.
+
+For more information on the docs context provider, see the [Continue documentation](https://docs.continue.dev/customize/deep-dives/docs).
+
+## Making different types of edits
+
+Granite.Code's edit feature was introduced in the [getting started tutorial](https://docs.granitecode.github.io/getting-started), where we saw how code can be easily made more readable. There are many other types of changes that can be made with Granite.Code. Some of these are available in the Granite.Code context menu in the code editor. This includes actions to:
+
+* Fix grammar and spelling mistakes
+* Fix code errors
+* Optimize code
+* Add code comments
+
+These menu items are a great way to access some of Granite.Code's editing features. They are also a great example of the different possibilities of the editing feature.
+
+## Using keyboard shortcuts for common contexts
+
+Granite.Code provides keyboard shortcuts for common contexts, which allow those contexts to be quickly used without needing to manually specify them.  The main shortcuts to know are:
+
+| Context      | Mac | Windows/Linux |
+|--------------|-----|---------------|
+| Current file | Option+Return  | Alt+Return  |
+| Codebase     | Command+Return | Ctrl+Return |

docs/conf.py

@@ -70,7 +70,7 @@
 html_logo = "img/logo.svg"
 
 # Set the explicit title of the HTML output
-html_title = 'Granite.code Documentation'
+html_title = 'Granite.Code Documentation'
 
 # add custom files that are stored in _static
 html_css_files = ['granite.css']

docs/configuration.md

@@ -0,0 +1,19 @@
+# Configuration
+
+Granite.Code includes a range of configuration options, which can be used to tailor it to your needs. There are two types of settings:
+
+## User settings
+
+These can be opened from the settings button in the Granite.Code, or by using the **Granite.Code: Open Settings** command. Example user settings include:
+
+* Wrapping codeblocks
+* Showing/hiding markdown formatting
+* Changing the font size
+
+## VS Code extension settings
+
+These can be opened from the VS Code settings, in the extensions section. VS Code extension settings include options such as:
+
+* Check for model updates
+* Tab autocompletion
+* Show inline tips

docs/getting-started.md

@@ -1,3 +1,96 @@
 # Getting Started
 
-FIXME
+This tutorial provides an introduction to the main features of Granite.Code. To complete it, we recommend that you have a running instance of VS Code with the Granite.Code extension enabled and setup.
+
+## Setup your workspace
+
+For the best experience, we recommend moving the Granite.Code chat to the secondary sidebar, so that it is visible alongside the code editor. To do this:
+
+1. If the secondary side bar is not visible, show it by clicking the **Toggle Secondary Side Bar** button in the VS Code header.
+2. Find the Granite.Code icon in the Activity Bar, then drag it to the secondary side bar header.
+
+Granite.Code should now be located next to the VS Code editor area. With that done, let's explore Granite.Code's features.
+
+## Ask questions
+
+Granite.Code provides an interactive chat feature, which can be used to ask the Granite models questions.
+
+To use the chat, either click on the "Ask anything" prompt, or use the **Command+L** / **Ctrl+L** keyboard shortcut. Then enter your question and press return.
+
+The Granite.Code assistant can answer a range of question types, including general coding knowledge questions, advice on particular coding problems, learning best practices, and generating example code. Here are some example questions that you can try out:
+
+1. TODO: general coding knowledge question. What is an X in Y?
+2. TODO: problem solving question. I am doing X. How do I do Y?
+3. TODO: best practices question. I am writing X. How do I make sure that it is performant?
+
+Once you have asked a question, you can ask follow-up questions about the model's response. For example, TODO.
+
+## Ask about a code section
+
+In addition to being able to ask general coding questions, you can also ask Granite.Code questions about sections of code. This can be useful for understanding how a piece of code works, or for asking how a section of code can be improved.
+
+To ask a question about a code section:
+
+1. Highlight the code you want to ask a question about.
+2. Use the **Command+L** / **Ctrl+L** keyboard shortcut to start a chat, or use the **Granite.Code → Add Highlighted Code to Context** context menu item.
+3. The code section will be shown in the chat prompt.
+4. Enter a question about the code in the chat prompt, and press return.
+
+You can try this using the code section below:
+
+1. Copy the section to a Python file.
+2. Highlight the code, and add it to the chat.
+3. In the chat prompt, ask: "what sorting algorithm is this?".
+
+```
+def sorting_algorithm(x):
+    for i in range(len(x)):
+        for j in range(len(x) - 1):
+            if x[j] > x[j + 1]:
+                x[j], x[j + 1] = x[j + 1], x[j]
+    return x
+```
+
+## Use Granite.Code to make changes
+
+With Granite.Code it is possible to make code changes by giving editing instructions to the Granite models. An easy way to try this is to edit a code section:
+
+1. In the editor, highlight the code you want to change.
+2. Use the **Command+E** / **Ctrl+E** keyboard shortcut to add the code section to the prompt and switch to edit mode.
+3. Describe how you want the code to be changed, then press return or click the **⏎ Enter** button.
+
+You can try this with the code section below:
+
+1. Copy the code section to the Python file you used earlier.
+2. Highlight the code and add it to the chat.
+3. In the chat, type "make this more readable", and press return.
+4. New code will be shown in the editor, alongside the existing code.
+5. Click Accept to accept the new code. Alternatively, you can use the **Command+Shift+Return** / **Ctrl+Shift+Return** keyboard shortcut to accept the changes.
+
+```
+def sorting_algorithm(x):
+    for i in range(len(x)):
+        for j in range(len(x) - 1):
+            if x[j] > x[j + 1]:
+                x[j], x[j + 1] = x[j + 1], x[j]
+    return x
+```
+
+## Autocompletion
+
+Granite.Code automatically makes suggestions as you type in the VS Code editor. Using the feature is simple: as you type you will see suggestions appear after the cursor. To accept a suggestion, just press the **Tab** key.
+
+Let's use autocompletion to write assertions for the sorting algorithms from the previous examples:
+
+* Copy the comment line below into the Python file that you used in the previous examples.
+* Place the cursor at the end of the line, then press **Return**.
+* When the suggestion is shown, press **Tab** to accept it.
+* You can keep pressing **Tab** to generate additional assertions for the other sorting algorithms in the file.
+
+```
+# Basic assertion for sorting_algorithm...
+```
+
+## Next steps
+
+This guide has introduced some essential Granite.Code features. However, there is much more to Granite.Code, including techniques which will allow you to get the most out of the features that have just been introduced. When you're ready, head over to the [best practices guide](https://docs.granitecode.github.io/best-practices) to learn more.

docs/granite-models.md

@@ -0,0 +1,5 @@
+# Granite Models
+
+Granite.Code automatically selects and downloads [Granite models](https://www.ibm.com/granite) in order to provide the best experience possible. It also automatically updates the models when new versions become available.
+
+To find out which model version you are currently using, click the **Models** button above the chat prompt.

docs/index.md

@@ -2,14 +2,23 @@
 
 # Granite.Code
 
-Granite.Code is a project by Red Hat and IBM to create an open-source AI code assistant using the IBM Granite model family, with the models running locally on your system.
+Granite.Code is an coding assistant for VS Code. It makes use of the [Granite family of AI models](https://www.ibm.com/granite) to provide a high quality AI assistant experience, while providing full control over privacy and information sharing. To achieve this, Granite.Code downloads and runs Granite models locally, so that no data is shared with other parties.
 
-The Granite.Code vscode extension is based on
-[Continue](https://github.com/continuedev/continue),
-but with a number of changes, including:
+Granite.Code can be installed as a VS Code extension: ee [setup](https://docs.granitecode.github.io/setup) to get started.
+
+## Get in Touch
+
+Issues can be reported in the [Granite.Code GitHub project](https://github.com/Granite-Code/granite-code/issues).
+
+## About Us
+
+Granite.Code is supported by [Red Hat](https://www.redhat.com/) and [IBM](https://www.ibm.com/), and is based on [Continue](https://github.com/continuedev/continue). The project is open source and contributions are welcome. For more details, see our [GitHub project](https://github.com/Granite-Code/).
 
 ```{toctree}
 :hidden:
-introduction.md
+setup.md
 getting-started.md
+best-practices.md
+configuration.md
+granite-models.md
 ```

docs/introduction.md

@@ -0,0 +1,20 @@
+# Setup
+
+Granite.Code is available as an extension [on the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=redhat.granitecode), and can be installed on Windows, Mac, and Linux.
+
+## Post-install setup
+
+Once you have installed Granite.Code, it is necessary to get the latest Granite models ready for local use. To do this, Granite.Code launches a setup wizard which sets up the environment and downloads the models.
+
+If you need to restart the setup wizard for any reason, it can be launched from the VS Code command palette using the `Granite.Code: Setup Granite as code assistant` command.
+
+Once you have set up Granite.Code, we recommend that you try out the [getting started tutorial](https://docs.granitecode.github.io/getting-started).
+
+## System requirements
+
+Granite.Code should only be used with hardware that is capable of effectively running the Granite models.
+
+Recommended hardware:
+
+* Mac: Apple Silicon systems with at least 20GB memory
+* Linux and Windows: systems with a discrete NVIDIA or AMD GPU