Repository: neovim/neovim
File: src/gen/gen_help_html.lua (Lua)

Code before:
---
--- @return nvim.gen_help_html.gen_result result
function M.gen(help_dir, to_dir, include, commit, parser_path)
  vim.validate('help_dir', help_dir, function(d)
    return vim.fn.isdirectory(vim.fs.normalize(d)) == 1
  end, 'valid directory')
  vim.validate('to_dir', to_dir, 'string')
  vim.validate('include', include, 'table', true)
  vim.validate('commit', commit, 'string', true)
  vim.validate('parser_path', parser_path, function(f)
    return vim.fn.filereadable(vim.fs.normalize(f)) == 1
  end, true, 'valid vimdoc.{so,dll} filepath')

  local err_count = 0
  local redirects_count = 0
  ensure_runtimepath()
  tagmap = get_helptags(vim.fs.normalize(help_dir))
  helpfiles = get_helpfiles(help_dir, include)
  to_dir = vim.fs.normalize(to_dir)
  parser_path = parser_path and vim.fs.normalize(parser_path) or nil

  print(('output dir: %s\n\n'):format(to_dir))
  vim.fn.mkdir(to_dir, 'p')
  gen_css(('%s/help.css'):format(to_dir))
  gen_tagindex_json(vim.fs.joinpath(to_dir, 'tagindex.json'))
  gen_tagindex_html(vim.fs.joinpath(to_dir, 'tagindex.html'))

  for _, f in ipairs(helpfiles) do
    -- "foo.txt"
    local helpfile = vim.fs.basename(f)
    -- "to/dir/foo.html"
    local to_fname = ('%s/%s'):format(to_dir, get_helppage(helpfile))
    local html, stats =
      gen_one(f, nil, to_fname, not new_layout[helpfile], commit or '?', parser_path)
    tofile(to_fname, html)
    print(
      ('generated (%-2s errors): %-15s => %s'):format(
        #stats.parse_errors,
        helpfile,
        vim.fs.basename(to_fname)
      )
    )

    -- Generate redirect pages for renamed help files.
    local helpfile_tag = (helpfile:gsub('%.txt$', ''))
    local redirect_from = redirects[helpfile_tag]
    if redirect_from then
      local redirect_text = ([[
*%s*      Nvim

This document moved to: |%s|

Review comment (suggestion):
let's name the html page `tag` (singular), it will live under `doc/tag.html`

```suggestion
  gen_tagindex_html(vim.fs.joinpath(to_dir, 'tag.html'))
```

Code after:
--- Generates HTML from :help docs located in `help_dir` and writes the result in `to_dir`.
---
--- Example:
---
---   gen('$VIMRUNTIME/doc', '/path/to/neovim.github.io/_site/doc/', {'api.txt', 'autocmd.txt', 'channel.txt'}, nil)
---
--- @param help_dir string Source directory containing the :help files. Must run `make helptags` first.
--- @param to_dir string Target directory where the .html files will be written.
--- @param include string[]|nil Process only these filenames. Example: {'api.txt', 'autocmd.txt', 'channel.txt'}
---
--- @return nvim.gen_help_html.gen_result result
function M.gen(help_dir, to_dir, include, commit, parser_path)
  vim.validate('help_dir', help_dir, function(d)
    return vim.fn.isdirectory(vim.fs.normalize(d)) == 1
  end, 'valid directory')
  vim.validate('to_dir', to_dir, 'string')
  vim.validate('include', include, 'table', true)
  vim.validate('commit', commit, 'string', true)
  vim.validate('parser_path', parser_path, function(f)
    return vim.fn.filereadable(vim.fs.normalize(f)) == 1
  end, true, 'valid vimdoc.{so,dll} filepath')

  local err_count = 0
  local redirects_count = 0
  ensure_runtimepath()
  tagmap = get_helptags(vim.fs.normalize(help_dir))
  helpfiles = get_helpfiles(help_dir, include)
  to_dir = vim.fs.normalize(to_dir)
  parser_path = parser_path and vim.fs.normalize(parser_path) or nil

  print(('output dir: %s\n\n'):format(to_dir))
  vim.fn.mkdir(to_dir, 'p')
  gen_css(('%s/help.css'):format(to_dir))
  gen_helptags_json(('%s/helptags.json'):format(to_dir))
  gen_helptag_html(('%s/helptag.html'):format(to_dir))

  for _, f in ipairs(helpfiles) do
    -- "foo.txt"
    local helpfile = vim.fs.basename(f)
    -- "to/dir/foo.html"
    local to_fname = ('%s/%s'):format(to_dir, get_helppage(helpfile))
    local html, stats =
      gen_one(f, nil, to_fname, not new_layout[helpfile], commit or '?', parser_path)
    tofile(to_fname, html)
    print(
      ('generated (%-2s errors): %-15s => %s'):format(
        #stats.parse_errors,
        helpfile,
        vim.fs.basename(to_fname)
      )
    )