From ee6f4ba06f640b49e116fd3e139548be4a573bd4 Mon Sep 17 00:00:00 2001 From: Micah Halter Date: Wed, 2 Aug 2023 11:44:50 -0400 Subject: [PATCH] docs: start adding documentation for configuration options --- config.ld | 4 ++ lua/astrocore/buffer.lua | 2 +- lua/astrocore/config.lua | 78 +++++++++++++++++++++++++++++++++++++-- lua/astrocore/init.lua | 2 +- lua/astrocore/mason.lua | 2 +- lua/astrocore/toggles.lua | 2 +- 6 files changed, 83 insertions(+), 7 deletions(-) diff --git a/config.ld b/config.ld index 7f61dbf..710ba93 100644 --- a/config.ld +++ b/config.ld @@ -1,7 +1,11 @@ project='AstroCore' title='AstroCore API' description='Documentation of AstroNvim\'s core API' +favicon = "https://astronvim.com/img/logo/favicon-16x16.png" +backtick_references = false format = 'markdown' file='lua' dir='docs' +readme = "README.md" +style = "!new" no_space_before_args=true diff --git a/lua/astrocore/buffer.lua b/lua/astrocore/buffer.lua index a488a0b..afb9542 100644 --- a/lua/astrocore/buffer.lua +++ b/lua/astrocore/buffer.lua @@ -5,7 +5,7 @@ -- This module can be loaded with `local buffer_utils = require "astrocore.buffer"` -- -- @module astrocore.buffer --- @copyright 2022 +-- @copyright 2023 -- @license GNU General Public License v3.0 local M = {} diff --git a/lua/astrocore/config.lua b/lua/astrocore/config.lua index aa0709c..b3d4c27 100644 --- a/lua/astrocore/config.lua +++ b/lua/astrocore/config.lua @@ -1,16 +1,88 @@ +--- ### AstroNvim Core Configuration +-- +-- This module simply defines the configuration table structure for `opts` used in: +-- +-- require("astrocore").setup(opts) +-- +-- @module astrocore.config +-- @copyright 2023 +-- @license GNU General Public License v3.0 + return { autocmds = {}, commands = {}, + --- Configuration of vim mappings to create + -- + -- @field mode The key, `mode` is the vim map mode (`:h map-modes`), and the value is a table of entries to be passed to `vim.keymap.set` (`:h vim.keymap.set`): + -- + -- The key is the first parameter or the vim mode (only a single mode supported) and the value is a table of keymaps within that mode: + -- + -- The first element with no key in the table is the action (the 2nd parameter) and the rest of the keys/value pairs are options for the third parameter. + -- @usage mappings = { + -- -- map mode (:h map-modes) + -- n = { + -- -- use vimscript strings for mappings + -- [""] = { ":w!", desc = "Save File" }, + -- -- navigate buffer tabs with `H` and `L` + -- L = { + -- function() + -- require("astronvim.utils.buffer").nav(vim.v.count > 0 and vim.v.count or 1) + -- end, + -- desc = "Next buffer", + -- }, + -- H = { + -- function() + -- require("astronvim.utils.buffer").nav(-(vim.v.count > 0 and vim.v.count or 1)) + -- end, + -- desc = "Previous buffer", + -- }, + -- -- tables with just a `desc` key will be registered with which-key if it's installed + -- -- this is useful for naming menus + -- ["b"] = { desc = "Buffers" }, + -- } + -- } mappings = {}, on_keys = {}, + --- Configuration table of features provided by AstroCore + -- @field autopairs enable or disable autopairs on start (boolean; default = true) + -- @field cmp enable or disable cmp on start (boolean; default = true) + -- @field highlighturl enable or disable highlighting of urls on start (boolean; default = true) + -- @field max_file table for defining the size of the max file for all features, above these limites we disable features like treesitter. This table has the fields: `size` (the number of bytes of a file) and `lines` (the number of lines of a file) + -- @field notifications enable or disable notifications on start (boolean; default = true) + -- @usage features = { + -- autopairs = true, + -- cmp = true, + -- highlighturl = true, + -- notiifcations = true, + -- max_file = { size = 1024 * 100, lines = 10000 }, + -- } features = { - max_file = { size = 1024 * 100, lines = 10000 }, -- set global limits for large files - autopairs = true, -- enable autopairs at start + autopairs = true, cmp = true, -- enable completion at start highlighturl = true, -- highlight URLs by default + max_file = { size = 1024 * 100, lines = 10000 }, notifications = true, -- disable notifications }, - git_worktrees = nil, -- enable git integration for detached worktrees (specify a table where each entry is of the form { toplevel = vim.env.HOME, gitdir=vim.env.HOME .. "/.dotfiles" }) + --- Enable git integration for detached worktrees (specify a list-like table where each entry is of the form `{ toplevel = vim.env.HOME, gitdir=vim.env.HOME .. "/.dotfiles" }`) + -- @table git_worktrees + -- @usage git_worktrees = { + -- { toplevel = vim.env.HOME, gitdir=vim.env.HOME .. "/.dotfiles" } + -- } + git_worktrees = nil, + --- Configuration table of session options for AstroNvim's session management powered by Resession + -- @field autosave a table with fields `last` and `cwd` to control if they should autosave sessions + -- @field ignore a table of lists for `dirs`, `filetypes`, and `buftypes` which should be ignored when autosaving sessions + -- @usage sessions = { + -- autosave = { + -- last = true, -- auto save last session + -- cwd = true, -- auto save session for each working directory + -- }, + -- ignore = { + -- dirs = {}, -- working directories to ignore sessions in + -- filetypes = { "gitcommit", "gitrebase" }, -- filetypes to ignore sessions + -- buftypes = {}, -- buffer types to ignore sessions + -- }, + -- } sessions = { autosave = { last = true, -- auto save last session diff --git a/lua/astrocore/init.lua b/lua/astrocore/init.lua index 31444e9..fd083ba 100644 --- a/lua/astrocore/init.lua +++ b/lua/astrocore/init.lua @@ -5,7 +5,7 @@ -- This module can be loaded with `local astro = require "astrocore"` -- -- @module astrocore --- @copyright 2022 +-- @copyright 2023 -- @license GNU General Public License v3.0 local M = {} diff --git a/lua/astrocore/mason.lua b/lua/astrocore/mason.lua index 316bec2..b5d77a9 100644 --- a/lua/astrocore/mason.lua +++ b/lua/astrocore/mason.lua @@ -6,7 +6,7 @@ -- -- @module astrocore.mason -- @see astrocore --- @copyright 2022 +-- @copyright 2023 -- @license GNU General Public License v3.0 local M = {} diff --git a/lua/astrocore/toggles.lua b/lua/astrocore/toggles.lua index f3a6975..8da1ad7 100644 --- a/lua/astrocore/toggles.lua +++ b/lua/astrocore/toggles.lua @@ -6,7 +6,7 @@ -- -- @module astrocore.toggles -- @see astrocore --- @copyright 2022 +-- @copyright 2023 -- @license GNU General Public License v3.0 local M = {}