mirror of
https://github.com/neovim/neovim.git
synced 2024-12-27 14:21:31 -07:00
docs(generators): bake into cmake
This commit is contained in:
parent
21152f7905
commit
2234b84a1b
6
.github/workflows/api-docs.yml
vendored
6
.github/workflows/api-docs.yml
vendored
@ -26,14 +26,10 @@ jobs:
|
|||||||
./.github/scripts/install_deps.sh
|
./.github/scripts/install_deps.sh
|
||||||
sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y doxygen python3 python3-msgpack
|
sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y doxygen python3 python3-msgpack
|
||||||
|
|
||||||
- name: Build metadata
|
|
||||||
run: |
|
|
||||||
make api-metadata
|
|
||||||
|
|
||||||
- name: Generate docs
|
- name: Generate docs
|
||||||
id: docs
|
id: docs
|
||||||
run: |
|
run: |
|
||||||
python3 scripts/gen_vimdoc.py
|
make doc
|
||||||
printf 'UPDATED_DOCS=%s\n' $([ -z "$(git diff)" ]; echo $?) >> $GITHUB_OUTPUT
|
printf 'UPDATED_DOCS=%s\n' $([ -z "$(git diff)" ]; echo $?) >> $GITHUB_OUTPUT
|
||||||
|
|
||||||
- name: FAIL, PR has not committed doc changes
|
- name: FAIL, PR has not committed doc changes
|
||||||
|
@ -242,6 +242,7 @@ add_glob_target(
|
|||||||
FLAGS -q
|
FLAGS -q
|
||||||
GLOB_DIRS runtime/ scripts/ src/ test/
|
GLOB_DIRS runtime/ scripts/ src/ test/
|
||||||
GLOB_PAT *.lua
|
GLOB_PAT *.lua
|
||||||
|
EXCLUDE runtime/lua/vim/_meta/.*
|
||||||
TOUCH_STRATEGY SINGLE)
|
TOUCH_STRATEGY SINGLE)
|
||||||
add_dependencies(lintlua-luacheck luacheck)
|
add_dependencies(lintlua-luacheck luacheck)
|
||||||
|
|
||||||
@ -253,7 +254,7 @@ add_glob_target(
|
|||||||
GLOB_PAT *.lua
|
GLOB_PAT *.lua
|
||||||
EXCLUDE
|
EXCLUDE
|
||||||
/runtime/lua/vim/re.lua
|
/runtime/lua/vim/re.lua
|
||||||
/runtime/lua/vim/_meta/options.lua
|
/runtime/lua/vim/_meta/.*
|
||||||
TOUCH_STRATEGY SINGLE)
|
TOUCH_STRATEGY SINGLE)
|
||||||
|
|
||||||
add_custom_target(lintlua)
|
add_custom_target(lintlua)
|
||||||
|
@ -274,13 +274,24 @@ Read [:help dev-doc][dev-doc-guide] to understand the expected documentation sty
|
|||||||
|
|
||||||
### Generating :help
|
### Generating :help
|
||||||
|
|
||||||
Many `:help` docs are autogenerated from (C or Lua) docstrings by the `./scripts/gen_vimdoc.py` script.
|
Many `:help` docs are autogenerated from (C or Lua) docstrings. To generate the documentation run:
|
||||||
For convenience you can filter the regeneration by target (api, lua, lsp) using the `-t` option, for example:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./scripts/gen_vimdoc.py -t lua
|
make doc
|
||||||
```
|
```
|
||||||
|
|
||||||
|
If you need to modify or debug the documentation flow, these are the main files:
|
||||||
|
- `./scripts/gen_vimdoc.py`:
|
||||||
|
Main doc generator. Drives doxygen to generate xml files, and scrapes those
|
||||||
|
xml files to render vimdoc files.
|
||||||
|
- `./scripts/lua2dox.lua`:
|
||||||
|
Used by `gen_vimdoc.py` to transform Lua files into a format compatible with doxygen.
|
||||||
|
- `./scripts/gen_eval_files.lua`:
|
||||||
|
Generates documentation and Lua type files from metadata files including:
|
||||||
|
- Eval functions (`src/nvim/eval.lua`)
|
||||||
|
- Options (`src/nvim/options.lua`)
|
||||||
|
- API
|
||||||
|
|
||||||
### Lua docstrings
|
### Lua docstrings
|
||||||
|
|
||||||
Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return
|
Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return
|
||||||
|
2
Makefile
2
Makefile
@ -131,7 +131,7 @@ functionaltest-lua: | nvim
|
|||||||
FORMAT=formatc formatlua format
|
FORMAT=formatc formatlua format
|
||||||
LINT=lintlua lintsh lintc clang-tidy lintcommit lint
|
LINT=lintlua lintsh lintc clang-tidy lintcommit lint
|
||||||
TEST=functionaltest unittest
|
TEST=functionaltest unittest
|
||||||
generated-sources benchmark $(FORMAT) $(LINT) $(TEST) api-metadata: | build/.ran-cmake
|
generated-sources benchmark $(FORMAT) $(LINT) $(TEST) doc: | build/.ran-cmake
|
||||||
$(CMAKE_PRG) --build build --target $@
|
$(CMAKE_PRG) --build build --target $@
|
||||||
|
|
||||||
test: $(TEST)
|
test: $(TEST)
|
||||||
|
@ -1,5 +1,8 @@
|
|||||||
#!/usr/bin/env -S nvim -l
|
#!/usr/bin/env -S nvim -l
|
||||||
-- Generator for src/nvim/eval.lua
|
-- Generator for various vimdoc and Lua type files
|
||||||
|
|
||||||
|
local DEP_API_METADATA = 'build/api_metadata.mpack'
|
||||||
|
local DEP_API_DOC = 'runtime/doc/api.mpack'
|
||||||
|
|
||||||
--- @class vim.api.metadata
|
--- @class vim.api.metadata
|
||||||
--- @field name string
|
--- @field name string
|
||||||
@ -168,11 +171,11 @@ end
|
|||||||
|
|
||||||
--- @return table<string, vim.EvalFn>
|
--- @return table<string, vim.EvalFn>
|
||||||
local function get_api_meta()
|
local function get_api_meta()
|
||||||
local mpack_f = assert(io.open('build/api_metadata.mpack', 'rb'))
|
local mpack_f = assert(io.open(DEP_API_METADATA, 'rb'))
|
||||||
local metadata = vim.mpack.decode(mpack_f:read('*all')) --[[@as vim.api.metadata[] ]]
|
local metadata = vim.mpack.decode(mpack_f:read('*all')) --[[@as vim.api.metadata[] ]]
|
||||||
local ret = {} --- @type table<string, vim.EvalFn>
|
local ret = {} --- @type table<string, vim.EvalFn>
|
||||||
|
|
||||||
local doc_mpack_f = assert(io.open('runtime/doc/api.mpack', 'rb'))
|
local doc_mpack_f = assert(io.open(DEP_API_DOC, 'rb'))
|
||||||
local doc_metadata = vim.mpack.decode(doc_mpack_f:read('*all')) --[[@as table<string,vim.gen_vim_doc_fun>]]
|
local doc_metadata = vim.mpack.decode(doc_mpack_f:read('*all')) --[[@as table<string,vim.gen_vim_doc_fun>]]
|
||||||
|
|
||||||
for _, fun in ipairs(metadata) do
|
for _, fun in ipairs(metadata) do
|
||||||
@ -282,7 +285,7 @@ end
|
|||||||
|
|
||||||
--- @return table<string, vim.EvalFn>
|
--- @return table<string, vim.EvalFn>
|
||||||
local function get_api_keysets_meta()
|
local function get_api_keysets_meta()
|
||||||
local mpack_f = assert(io.open('build/api_metadata.mpack', 'rb'))
|
local mpack_f = assert(io.open(DEP_API_METADATA, 'rb'))
|
||||||
|
|
||||||
--- @diagnostic disable-next-line:no-unknown
|
--- @diagnostic disable-next-line:no-unknown
|
||||||
local metadata = assert(vim.mpack.decode(mpack_f:read('*all')))
|
local metadata = assert(vim.mpack.decode(mpack_f:read('*all')))
|
||||||
|
@ -1359,7 +1359,4 @@ if __name__ == "__main__":
|
|||||||
else:
|
else:
|
||||||
main(Doxyfile, args)
|
main(Doxyfile, args)
|
||||||
|
|
||||||
print('Running ./scripts/gen_eval_files.lua')
|
|
||||||
subprocess.call(['./scripts/gen_eval_files.lua'])
|
|
||||||
|
|
||||||
# vim: set ft=python ts=4 sw=4 tw=79 et :
|
# vim: set ft=python ts=4 sw=4 tw=79 et :
|
||||||
|
@ -281,16 +281,17 @@ set(UNICODE_TABLES_GENERATOR ${GENERATOR_DIR}/gen_unicode_tables.lua)
|
|||||||
set(UNICODE_DIR ${PROJECT_SOURCE_DIR}/src/unicode)
|
set(UNICODE_DIR ${PROJECT_SOURCE_DIR}/src/unicode)
|
||||||
set(GENERATED_UNICODE_TABLES ${GENERATED_DIR}/unicode_tables.generated.h)
|
set(GENERATED_UNICODE_TABLES ${GENERATED_DIR}/unicode_tables.generated.h)
|
||||||
set(VIM_MODULE_FILE ${GENERATED_DIR}/lua/vim_module.generated.h)
|
set(VIM_MODULE_FILE ${GENERATED_DIR}/lua/vim_module.generated.h)
|
||||||
set(LUA_EDITOR_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/_editor.lua)
|
set(NVIM_RUNTIME_DIR ${PROJECT_SOURCE_DIR}/runtime)
|
||||||
set(LUA_SHARED_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/shared.lua)
|
set(LUA_EDITOR_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/_editor.lua)
|
||||||
set(LUA_LOADER_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/loader.lua)
|
set(LUA_SHARED_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/shared.lua)
|
||||||
set(LUA_INSPECT_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/inspect.lua)
|
set(LUA_LOADER_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/loader.lua)
|
||||||
set(LUA_FS_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/fs.lua)
|
set(LUA_INSPECT_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/inspect.lua)
|
||||||
set(LUA_F_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/F.lua)
|
set(LUA_FS_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/fs.lua)
|
||||||
set(LUA_OPTIONS_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/_options.lua)
|
set(LUA_F_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/F.lua)
|
||||||
set(LUA_FILETYPE_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/filetype.lua)
|
set(LUA_OPTIONS_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/_options.lua)
|
||||||
set(LUA_INIT_PACKAGES_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/_init_packages.lua)
|
set(LUA_FILETYPE_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/filetype.lua)
|
||||||
set(LUA_KEYMAP_MODULE_SOURCE ${PROJECT_SOURCE_DIR}/runtime/lua/vim/keymap.lua)
|
set(LUA_INIT_PACKAGES_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/_init_packages.lua)
|
||||||
|
set(LUA_KEYMAP_MODULE_SOURCE ${NVIM_RUNTIME_DIR}/lua/vim/keymap.lua)
|
||||||
set(CHAR_BLOB_GENERATOR ${GENERATOR_DIR}/gen_char_blob.lua)
|
set(CHAR_BLOB_GENERATOR ${GENERATOR_DIR}/gen_char_blob.lua)
|
||||||
set(LUAJIT_RUNTIME_DIR ${DEPS_PREFIX}/share/luajit-2.1/jit)
|
set(LUAJIT_RUNTIME_DIR ${DEPS_PREFIX}/share/luajit-2.1/jit)
|
||||||
|
|
||||||
@ -857,6 +858,57 @@ add_custom_target(generated-sources DEPENDS
|
|||||||
${NVIM_GENERATED_SOURCES}
|
${NVIM_GENERATED_SOURCES}
|
||||||
)
|
)
|
||||||
|
|
||||||
add_custom_target(api-metadata DEPENDS ${API_METADATA})
|
|
||||||
|
|
||||||
add_subdirectory(po)
|
add_subdirectory(po)
|
||||||
|
|
||||||
|
#-------------------------------------------------------------------------------
|
||||||
|
# Docs
|
||||||
|
#-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
set(VIMDOC_FILES
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/api.mpack
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/api.txt
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/diagnostic.mpack
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/diagnostic.txt
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/lsp.mpack
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/lsp.txt
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/lua.mpack
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/lua.txt
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/treesitter.mpack
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/treesitter.txt
|
||||||
|
)
|
||||||
|
|
||||||
|
glob_wrapper(API_SOURCES ${PROJECT_SOURCE_DIR}/src/nvim/api/*.c)
|
||||||
|
glob_wrapper(LUA_SOURCES ${NVIM_RUNTIME_DIR}/lua/vim/*.lua)
|
||||||
|
|
||||||
|
add_custom_command(
|
||||||
|
OUTPUT ${VIMDOC_FILES}
|
||||||
|
COMMAND ${PROJECT_SOURCE_DIR}/scripts/gen_vimdoc.py
|
||||||
|
DEPENDS ${API_SOURCES} ${LUA_SOURCES}
|
||||||
|
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
|
||||||
|
)
|
||||||
|
|
||||||
|
set(GEN_EVAL_FILES
|
||||||
|
${NVIM_RUNTIME_DIR}/lua/vim/_meta/vimfn.lua
|
||||||
|
${NVIM_RUNTIME_DIR}/lua/vim/_meta/api.lua
|
||||||
|
${NVIM_RUNTIME_DIR}/lua/vim/_meta/api_keysets.lua
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/builtin.txt
|
||||||
|
${NVIM_RUNTIME_DIR}/lua/vim/_meta/options.lua
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/options.txt
|
||||||
|
)
|
||||||
|
|
||||||
|
add_custom_command(
|
||||||
|
OUTPUT ${GEN_EVAL_FILES}
|
||||||
|
COMMAND ${PROJECT_SOURCE_DIR}/scripts/gen_eval_files.lua
|
||||||
|
DEPENDS
|
||||||
|
${API_METADATA}
|
||||||
|
${PROJECT_SOURCE_DIR}/scripts/gen_eval_files.lua
|
||||||
|
${PROJECT_SOURCE_DIR}/src/nvim/eval.lua
|
||||||
|
${PROJECT_SOURCE_DIR}/src/nvim/options.lua
|
||||||
|
${NVIM_RUNTIME_DIR}/doc/api.mpack
|
||||||
|
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
|
||||||
|
)
|
||||||
|
|
||||||
|
add_custom_target(doc
|
||||||
|
DEPENDS ${VIMDOC_FILES} ${GEN_EVAL_FILES}
|
||||||
|
)
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user