chore(build): auto-generate docs

docs/design.md

@@ -10,20 +10,21 @@ categories:
 # General
 
 There is the [care.nvim](https://github.com/max397574/care.nvim) plugin. This is
-the main module of the whole completion architecture. Then there are also sources, which is where
-the core gets it's completions from.
+the main module of the whole completion architecture. Then there are also
+sources, which is where the core gets it's completions from.
 
 ## Care.nvim
 
-This is the core of the autocompletion. From here the sources are used to get completions which
-are then displayed in the [Completion Menu](#completion-menu)
+This is the core of the autocompletion. From here the sources are used to get
+completions which are then displayed in the [Completion Menu](#completion-menu)
 
 ### Completion Menu
 
-The completion menu displays the current completions.
-Features that it should have:
+The completion menu displays the current completions. Features that it should
+have:
 
-- Completely customizable display for every entry (with **text-highlight chunks** like extmark-api)
+- Completely customizable display for every entry (with **text-highlight
+  chunks** like extmark-api)
 - Customizable scrollbar
 - Customizable window properties
   - Border
@@ -37,8 +38,8 @@ Features that it should have:
 
 ## Offset
 
-Offset always describes the distance between e.g. the start of an entry from the beginning of the
-line.
+Offset always describes the distance between e.g. the start of an entry from the
+beginning of the line.
 
 # Architecture
 
@@ -49,12 +50,14 @@ autocompletion:
 1. `TextChangedI` or `CursorMovedI`
 2. get the context (line before, cursor position etc)
 3. Check if context changed
-4. Check if character was a trigger character or completion was triggered manually
+4. Check if character was a trigger character or completion was triggered
+   manually
 5. Depending on ^^ decide what to do _for every source_:
    - Get new completions
      1. get completions from source based on context
    - sort completions
-     1. Use characters found with `keyword_pattern` to fuzzy match and sort completions
+     1. Use characters found with `keyword_pattern` to fuzzy match and sort
+        completions
 6. Collect all the completions
 7. Open menu to display thing
    1. if there is a selected one:
@@ -76,135 +79,108 @@ When completing (e.g. `<cr>`):
 
 ## Nvim-cmp
 
-These days nvim-cmp is the most popular completion-engine for neovim. There are some mayor issues
-me and also other people in the community have with cmp.
+These days nvim-cmp is the most popular completion-engine for neovim. There are
+some mayor issues me and also other people in the community have with cmp.
 
 ### Bad code/Documentation
 
-The code of nvim-cmp is often quite unreadable. Sometimes this might be due to optimizations
-and surely some of it has just grown historically. Also there are nearly no docs on how the
-whole completion engine works. The api for new sources is quite unclear and far from optimal.
-While this doesn't really matter to a user it definitely does to a potential contributor and
-developers of sources.
+The code of nvim-cmp is often quite unreadable. Sometimes this might be due to
+optimizations and surely some of it has just grown historically. Also there are
+nearly no docs on how the whole completion engine works. The api for new sources
+is quite unclear and far from optimal. While this doesn't really matter to a
+user it definitely does to a potential contributor and developers of sources.
 
 ### Legacy code/features
 
-There are a lot of things which grew just historically. The author of nvim-cmp is
-(understandable to a certain degree) afraid of making breaking changes and fixing them or just
-doesn't think changes are necessary.
+There are a lot of things which grew just historically. The author of nvim-cmp
+is (understandable to a certain degree) afraid of making breaking changes and
+fixing them or just doesn't think changes are necessary.
 
 #### Configuration of item display
 
-One such example is the configuration of how items are displayed in the menu. This works with
-a function `formatting` which takes a completion item and is allowed to return an item where
-the three fields `menu`, `kind` and `abbr` and three more fields for highlights for those can
-be set. So apart from the background and border color of the menu you're limited to have three
-different fields and colors in your menu E.g. source name, kind name, kind icon and text isn't
-possible. It's also not possible to have round or half blocks around icons because you don't
-have enough colors. An example of an issue can be found [here](https://github.com/hrsh7th/nvim-cmp/issues/1599).
-You also can't add padding wherever you want and you can't align the fields as you want.
+One such example is the configuration of how items are displayed in the menu.
+This works with a function `formatting` which takes a completion item and is
+allowed to return an item where the three fields `menu`, `kind` and `abbr` and
+three more fields for highlights for those can be set. So apart from the
+background and border color of the menu you're limited to have three different
+fields and colors in your menu E.g. source name, kind name, kind icon and text
+isn't possible. It's also not possible to have round or half blocks around icons
+because you don't have enough colors. An example of an issue can be found
+[here](https://github.com/hrsh7th/nvim-cmp/issues/1599). You also can't add
+padding wherever you want and you can't align the fields as you want.
 
 #### Legacy code
 
-There is e.g. the whole "native menu" thing laying around in the codebase. Nowadays this isn't
-really needed anymore. Everything of it can be accomplished with the "custom menu". There is a
-lot of duplicate code because of that.
+There is e.g. the whole "native menu" thing laying around in the codebase.
+Nowadays this isn't really needed anymore. Everything of it can be accomplished
+with the "custom menu". There is a lot of duplicate code because of that.
 
 ### Mapping system
 
-The mapping system is quite confusing. It's a table in the config with keys to be mapped as keys
-and a call to `cmp.mapping()` with a callback to the actual functionality as value.
-Users should able to just use normal mappings or functions with `vim.keymap.set`.
+The mapping system is quite confusing. It's a table in the config with keys to
+be mapped as keys and a call to `cmp.mapping()` with a callback to the actual
+functionality as value. Users should able to just use normal mappings or
+functions with `vim.keymap.set`.
 
 ### Custom solutions for builtin functionality
 
-An example for this is the [Mapping system](#mapping-system). Another example would be the `cmp.event.on`
-which could just be done with User autocmds.
+An example for this is the [Mapping system](#mapping-system). Another example
+would be the `cmp.event.on` which could just be done with User autocmds.
 
 ### Why not contribute?
 
-The maintainer is in general quite conservative. There were pull-requests for many features open
-which were liked by the community (seen by reactions and comments). But they were abandoned
-because the maintainer saw no reason to add it. There was for example a pull-request to fix the
-issue with the limited fields in the configuration [here](https://github.com/hrsh7th/nvim-cmp/pull/1238).
-This pull request was closed because _No specific use cases have emerged at this stage._
-according to the author. Even though there was clearly a problem described and what the pr would
-allow (this pr allowed custom fields which still isn't nice but fixed the obvious problems).
-There were also some features (in particular the custom scrollbars) removed because there were
-some issues with it which apparently weren't worth fixing for the feature.
-So it's not really motivating to try to contribute new things. It's also quite hard because of
-the messy code with lots of legacy code.
+The maintainer is in general quite conservative. There were pull-requests for
+many features open which were liked by the community (seen by reactions and
+comments). But they were abandoned because the maintainer saw no reason to add
+it. There was for example a pull-request to fix the issue with the limited
+fields in the configuration
+[here](https://github.com/hrsh7th/nvim-cmp/pull/1238). This pull request was
+closed because _No specific use cases have emerged at this stage._ according to
+the author. Even though there was clearly a problem described and what the pr
+would allow (this pr allowed custom fields which still isn't nice but fixed the
+obvious problems). There were also some features (in particular the custom
+scrollbars) removed because there were some issues with it which apparently
+weren't worth fixing for the feature. So it's not really motivating to try to
+contribute new things. It's also quite hard because of the messy code with lots
+of legacy code.
 
 # Goals
 
 ## Use nvim-cmp sources
 
-We should be able to use nvim-cmp sources. This should be possible by adding a `package.loaders`
-where we can redirect calls to `cmp.register_source` (which happens in most sources auto-
-matically) to our own plugin. We **don't want to adapt to cmp's apis** for this though. We won't
-extend our own formats e.g. for entries or sources to match cmps. Even when it's complicated we
-will just convert between the different formats.
+We should be able to use nvim-cmp sources. This should be possible by adding a
+`package.loaders` where we can redirect calls to `cmp.register_source` (which
+happens in most sources auto- matically) to our own plugin. We **don't want to
+adapt to cmp's apis** for this though. We won't extend our own formats e.g. for
+entries or sources to match cmps. Even when it's complicated we will just
+convert between the different formats.
 
 ## Native things
 
-Use as many native things as possible. This includes setting mappings with `vim.keymap.set` or
-add events as user autocmd events.
+Use as many native things as possible. This includes setting mappings with
+`vim.keymap.set` or add events as user autocmd events.
 
 # Non-Goals
 
 ## Different views
 
-Nvim-cmp has different views. At the moment wild-menu, native menu and custom menu. There is a
-lot of code duplication because of this. We'd like to avoid having multiple views. The native
-one isn't needed anyway (it likely is just in cmp for historical reasons).
-In the future we'd like to allow injecting custom views via config where you just get the
-entries and do things with them yourself. This is mostly to avoid code duplication in core.
+Nvim-cmp has different views. At the moment wild-menu, native menu and custom
+menu. There is a lot of code duplication because of this. We'd like to avoid
+having multiple views. The native one isn't needed anyway (it likely is just in
+cmp for historical reasons). In the future we'd like to allow injecting custom
+views via config where you just get the entries and do things with them
+yourself. This is mostly to avoid code duplication in core.
 
 ## Commandline completion
 
-At the moment no command line completion is planned. This is because the author thinks it's not
-really needed because builtin completion is already quite good and there is little value added
-by adding commandline completion. Also it doesn't really make sense in my opinion to combine
-commandline completion and autocompletion for buffer contents in the same plugin. Especially if
-you try to share things in between like nvim-cmp does.
+At the moment no command line completion is planned. This is because the author
+thinks it's not really needed because builtin completion is already quite good
+and there is little value added by adding commandline completion. Also it
+doesn't really make sense in my opinion to combine commandline completion and
+autocompletion for buffer contents in the same plugin. Especially if you try to
+share things in between like nvim-cmp does.
 
 # Types used
 
-The types should minimally be the lsp things (for the context passed to source, for response and
-for entries). Everything additionally is mostly optional.
-
-# Code style
-
-## Object-Orientation
-
-Most of the modules are written object oriented. This decision was made because it's way easier
-to create new instances of the things and associate data with them.
-
-## Functions
-
-You should always write functions in the form of `[local] function <name>(<parameters>)` as
-opposed to `[local <name> = function(<parameters>)`. The first notation provides the advantage
-that you can directly jump to it's definition and you won't get multiple results (the name and
-the anonymous function).
-
-## Comments and annotations
-
-Add annotations to **every** public function of a module (e.g. with neogen) and add comments
-explaining what the code does. We'd like to have code which would be understandable for outsiders.
-Also try to add annotations and descriptions to local functions but this isn't as important as
-public ones
-
-### Format
-
-For The annotations we use [LuaCATS](https://luals.github.io/wiki/annotations/) style. For types
-don't use a space after the `---` marker. For comments you should. Check the annotations in
-`lua/care/types/` for examples.
-
-## Types
-
-We have files for types which are tangled from a norg file (this one?) using lua-ls annotations.
-They are prefixed with `care.`.
-As often as possible we should try to use the `lsp.*` types which are in neovim core.
-
-The types are documented in the `docs/` folder and are tangled to lua type files with [neorg](https://github.com/nvim-neorg/neorg).
-So if you want to change a type annotation you should change the `.norg` file and tangle it again.
+The types should minimally be the lsp things (for the context passed to source,
+for response and for entries). Everything additionally is mostly optional.

docs/dev/code_style.md

@@ -0,0 +1,42 @@
+# Code style
+
+## Object-Orientation
+
+Most of the modules are written object oriented. This decision was made because
+it's way easier to create new instances of the things and associate data with
+them.
+
+The tables of which the modules consist should be named with uppercase letters
+(e.g. `Menu`). This should be done in the definition and when using them.
+Instances should use lowercase letters.
+
+## Functions
+
+You should always write functions in the form of
+`[local] function <name>(<parameters>)` as opposed to
+`[local <name> = function(<parameters>)`. The first notation provides the
+advantage that you can directly jump to it's definition and you won't get
+multiple results (the name and the anonymous function).
+
+## Comments and annotations
+
+Add annotations to **every** public function of a module (e.g. with neogen) and
+add comments explaining what the code does. We'd like to have code which would
+be understandable for outsiders. Also try to add annotations and descriptions to
+local functions but this isn't as important as public ones
+
+### Format
+
+For The annotations we use [LuaCATS](https://luals.github.io/wiki/annotations/)
+style. For types don't use a space after the `---` marker. For comments you
+should. Check the annotations in `lua/care/types/` for examples.
+
+## Types
+
+We have files for types which are tangled from a norg file (this one?) using
+lua-ls annotations. They are prefixed with `care.`. As often as possible we
+should try to use the `lsp.*` types which are in neovim core.
+
+The types are documented in the `docs/` folder and are tangled to lua type files
+with [neorg](https://github.com/nvim-neorg/neorg). So if you want to change a
+type annotation you should change the `.norg` file and tangle it again.

docs/dev/index.md

@@ -8,6 +8,9 @@ description: Ressources to devlop care.nvim or sources for it
 This is the internal documentation of the care.nvim code base. It also includes
 documentation for developing sources for care.nvim.
 
+If you want to contribute you should read the
+[code style documentation](./code_style).
+
 ## Conventions used
 
 For describing classes there is always a section for methods (functions) and one