add docs

Author: rdmsr

CONFIG.md

@@ -0,0 +1,54 @@
+# Configuration options
+The configuration file is a TOML file with the following sections:
+
+## `project`
+- `name`: Project name.
+- `version`: Project version.
+
+## `input`
+- `glob`: Glob to use for finding documented files.
+- `compiler_arguments`: List of arguments to pass to libclang while parsing code.
+
+
+## `output`
+- `static_dir`: Path to a directory containing static files that will be copied in the output directory, this is where `style.css` will typically be located.
+- `path`: Path to the output directory.
+- `root_namespace` (optional): Namespace to use as the root, this is useful for libraries that only globally expose one namespace and want the index to be based on that namespace.
+- `base_url`: Base URL to prepend all paths with.
+
+## `pages`
+- `index` (optional): Markdown file to use as the index file, if an index page is not specified, the root namespace's comment will be used instead.
+- `extra` (optional): List of file paths to serve as extra documentation pages.
+
+## `doctests` (optional)
+- `enable`: Whether to enable documentation tests or not.
+- `run`: Whether to run documentation tests or not (if disabled, tests will only be compiled).
+- `compiler_invocation`: Compiler invocation to use to compile documentation tests, this is represented as an array containing `argv`. The sentinel values `{file}` and `{out}` are replaced at runtime by the appropriate values.
+
+
+# Example
+
+```toml
+[project]
+name = "Example"
+version = "0.1.0"
+
+[input]
+glob = "include/**/*.hpp"
+compiler_arguments = ["-Iinclude", "-std=gnu++20", "-xc++"]
+
+[pages]
+index = "README.md"
+extra = ["extra-page.md"]
+
+[output]
+static_dir = "static"
+path = "docs"
+base_url = "/cppdoc"
+
+[doctests]
+enable = false 
+run = true
+compiler_invocation = ["clang++", "{file}", "-o", "{out}", "-Iinclude", "-std=c++20"]
+```
+

README.md

@@ -10,5 +10,20 @@ cppdoc is a C++ documentation generator inspired by `rustdoc`
 - libclang-based parser with support for records, enums, functions and namespaces
 - Fair performance, with generation usually being faster than clang-backed Doxygen
 
+## Usage
+See [USAGE.md](USAGE.md)
+
 ## Preview
-Screenshot soon :tm:
+There is a live demo available [here](https://rdmsr.github.io/cppdoc).
+
+Here is what cppdoc looks like with three different stylesheets:
+
+`example/static/light.css`:
+![light preview](assets/light-preview.png)
+
+`example/static/ayu.css`:
+![ayu preview](assets/ayu-preview.png)
+
+`example/static/gruvbox.css`:
+![gruvbox preview](assets/gruvbox-preview.png)
+

USAGE.md

@@ -0,0 +1,113 @@
+# Usage
+Projects using `cppdoc` must have a `cppdoc.toml` configuration file, see [CONFIG.md](CONFIG.md) for the available configuration options.
+
+## Command-line options:
+To build documentation for a project:
+
+```
+cppdoc build
+```
+
+To output JSON representing the codebase:
+
+```
+cppdoc build -d
+```
+
+More command-line options can be displayed using `-h` or `--help`.
+
+
+## Comments
+Comments are written using `///` or `//<`, the latter being used for inline documentation, as such:
+
+```cpp
+/// Documentation for 'MyEnum'
+enum MyEnum {
+	A //< Documentation for 'A' 
+}
+```
+
+Comments content are parsed as cppdoc-flavored markdown, there is no support for `javadoc`/Doxygen-style comments.
+
+## Markdown syntax
+`cppdoc` introduces a few extensions to markdown.
+
+- To link documentation objects, one must prefix the link path with `::`. For example:
+
+```
+See [MyStruct](::MyStruct)
+```
+
+- Mermaid graphs can be displayed using `mermaid` codeblocks:
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+## Documentation tests
+`cppdoc` supports running documentation tests akin to `rustdoc`, these tests are written in `cpp` and `c++` codeblocks and help ensure that code examples are up-to-date with API usage.
+
+Documentation codeblocks feature special syntax:
+- Lines prefixed with `@` won't be displayed, but will be added to the source code:
+
+```
+@int a = 1;
+int b = a + 2;
+```
+
+Will only display:
+
+```
+int b = a + 2;
+```
+
+But will be compiled fully, that is with `int a = 1` included.
+
+
+- Similarly, `@include` allows for quiet inclusion of a header file:
+
+```
+@include "file.h"
+int a = 1;
+```
+
+Will only display:
+
+```
+int a = 1;
+```
+
+Notice that documentation tests don't need a `main` function, this is because documentation tests run by default in `main`, to disable this behavior one must set the codeblock language to `nomain` instead of `c++` or `cpp`.
+
+
+### Test framework
+`cppdoc` includes a basic test framework for documentation tests, this is useful for testing that examples still run successfully.
+The following macros are defined:
+
+- `ASSERT` and `ASSERT_EQ`: test for truth and equality, respectively
+- `ASSERT_FALSE` and `ASSERT_NE`: test for falsity and inequality, respectively
+- `ASSERT_GT` and `ASSERT_LT`: test for greater than and less than, respectively
+- `ASSERT_GE` and `ASSERT_LE`: test for greater than or equal and less than or equal, respectively
+
+Therefore, it is possible to write code like so:
+
+```c++
+int a = 1;
+
+ASSERT(a == 1);
+```
+
+The code above will compile and run successfuly, but the following code will fail to run:
+
+```c++
+int a = 2;
+ASSERT(a == 1);
+```
+
+
+# Styling
+`cppdoc` expects a `style.css` file to be present at the root of the generated documentation. It is recommended to put the stylesheets in a static directory and set the `static` option in the configuration file.

assets/ayu-preview.png

@@ -1,4 +1,4 @@
-@import "light.css";
+@import "ayu.css";
 
 body {
     font-family: var(--font-secondary);
@@ -224,4 +224,4 @@ div.sidebar a {
     .item-table .item-desc * {
         margin-left: 20px;
     }
-}
+}