Fix docs

.pre-commit-config.yaml

@@ -8,6 +8,7 @@ repos:
     rev: v4.5.0
     hooks:
     - id: check-added-large-files
+      exclude: ^.*\.gif$
     - id: check-ast
     - id: check-case-conflict
     - id: check-merge-conflict

README.md

@@ -1,23 +1,63 @@
-# Souffle Analyzer
+# souffle-analyzer
 
-A language server bundled with other utilities for the [Souffle language](https://souffle-lang.github.io/).
+souffle-analyzer is a [language server](https://microsoft.github.io/language-server-protocol) for the [Souffle logic programming language](https://souffle-lang.github.io/).
 
+![](./docs/img/navigation.gif)
+
+The code in the demonstration GIF above is from the [cclyzer++](https://github.com/galoisinc/cclyzerpp) project.
 
 ## Features
 
-### Go To Definition
+It is still early days for the project, so do expect things to be a bit rough around the edges.
+
+The following language server capabilities are currently available at both file level and workspace level:
+
+- Go to defintion
+  - for relations and types
+- Go to type defintion
+  - for constant or variable attributes within relation references or facts
+- Go to references
+  - for relations
+- Basic code completion
+- Hover
+  - for relations and types
+- Code actions
+  - generate docstring template for relation declarations
+- Basic diagnostics
 
-![](./docs/img/go-to-defintion.gif)
 
-### Hover Documentation
+## Try it out
 
-![](./docs/img/hover.gif)
+See [./docs/usage.md](./docs/usage.md).
 
-### Code Actions
 
-![](./docs/img/code-action.gif)
+## Philosophy
+
+The project was initially built with the following criteria in mind:
+
+* **We hope everyone getting to know the project can try it**.
+  * For potential users, we try to support all 3 operating systems Windows, Linux, and MacOS to certain extends: all tests should pass and the project should build successfully on any supposedly supported platform.
+  * For people wanting to hack on the project, we also make sure the project works on [all supported Python versions still currently under LTS](https://devguide.python.org/versions/#supported-versions) and reasonably easy to set up. Supporting all versions of Python also allow us to think about publishing a library from the project later on.
+* **We value user experience and stability**. We aim for extensive testing, minimum amount of bugs, and reasonably good performance.
 
 
 ## Roadmap
 
-T.B.D.
+In the near future, we will focus on the following items:
+
+* Obtain higher support coverage over the syntax of the Souffle language. Although the tree-sitter parser works quite well, we have not fully support every construct of the language within the language server itself.
+* Investigate the well-known [UTF-16 encoding-related issue](https://github.com/Microsoft/language-server-protocol/issues/376), which is likely to cause some bugs.
+* Stabilize and enhance the currently-available capabilities. A reasonable amount of effort will be spent in:
+  * Type inference and semantic checking for better diagnostics and hover.
+  * Handle import relationship between files.
+  * More accurate and faster code completion.
+
+Some other features that we will consider:
+
+* Add support for more complex but reasonably useful capabilities, especially refactoring-related ones such as rename.
+* Support for C-style macros, which is in and of itself an interesting technical problem.
+
+
+## You may ask...
+
+See [./docs/faq.md](./docs/faq.md).

docs/faq.md

@@ -0,0 +1,5 @@
+1. Why Python?
+
+It is not my favourite language, and I doubt I really have one for all problems/projects. I started out the project being very familiar with Python after two years of learning, using, and trying to get really good at it. One day, I just told myself to start this off before decision fatique kicked in among myriads of different things to think about. Although Python does not sound like the best option being one of the slower languages out there, I can definitely see myself rewriting it in something else once we cross that bridge of bad performance and excessive memory usage severely affecting user experience without clear solutions other than to use a better language in these aspects.
+
+The original parser is a tree-sitter parser, which allows for implementing the language server in a few other languages. The closest contender was Rust, but it will most likely be chosen for a rewrite (if there will ever be one) rather than being the language to start off with.

docs/usage.md

@@ -0,0 +1,56 @@
+# Using souffle-analyzer
+
+To try using souffle-analyzer, you need two things:
+
+* The server, which is a souffle-analyzer executable.
+* The client, which is a compatible text editor.
+
+## The language server executable
+
+You can access the pre-built executables in the project's [Release page](https://github.com/nathanwn/souffle-analyzer/releases/tag/nightly). Note: At the moment, we only offer the pre-release/nightly version.
+
+Alternatively, you can build the server from source if you choose to. Just clone the project, create a virtual environment, and do `pip install .`.
+
+## Text editors
+
+### VS Code
+
+We offer a `.vsix` VS Code extension that wires the language server to VS Code, which could also be found in the project's [Release page](https://github.com/nathanwn/souffle-analyzer/releases/tag/nightly).
+
+To install the plugin from the `.vsix` file in VS Code: `Extensions` -> `Views and More Actions` (the three-dot button) -> `Install from VSIX...`, and choose the `.vsix` file you downloaded.
+
+### Neovim
+
+For Neovim, there should be multiple ways to do it. The following is just one of the methods that has been working well for me. (Note: requires Neovim >= 0.8)
+
+1. Add the `souffle` filetype. In your `filetype.lua` file:
+
+```lua
+vim.filetype.add({
+  extension = {
+    dl = "souffle",
+  },
+})
+```
+
+2. Create an auto command triggered on the `FileType` event to start souffle-analyzer:
+
+```lua
+vim.api.nvim_create_autocmd("FileType", {
+    pattern = { "souffle" },
+    callback = function()
+        vim.lsp.start({
+            name = "souffle-analyzer",
+            cmd = {
+                "souffle-analyzer",  -- or path to the executable if it is not in PATH
+                "server",
+            },
+            root_dir = vim.fs.dirname(vim.fs.find({ ".git" }, { upward = true })[1]),
+        })
+    end,
+})
+```
+
+## Other text editors
+
+As long as your text editor supports LSP, you will probably have no problem using `souffle-analyzer` once you figure out how to configure LSP for your editor.