Problem:
In h2 headings, the first tag points to an invalid anchor. This used to
work but regressed a few months ago, possibly related to
ceea6898a8.
Solution:
- Simplify the logic, don't try to be clever:
- Always use to_heading_tag() for the h2 `id`.
- Also:
- Render tags as `<span>`, because `<code>` is unnecessary and doesn't
look great in headings.
- In the main h1, use "foo.txt" as the anchor `name` (rarely used),
prefer the next found tag for the `href`.
Problem:
The <br> hack in a0c64fe816 causes weird layout if a "h4 pseudo-heading"
is not the only tag on the line. For example in the help text below, the
"*'buflisted'*" tag was treated as h4 and followed by <br>, which is
obviously wrong:
*'buflisted'* *'bl'* *'nobuflisted'* *'nobl'* *E85*
'buflisted' 'bl' boolean (default on)
Solution:
Only treat a tag as "h4 pseudo-heading" if it is the only tag in the
line. This is fragile, but in practice seems to get the right balance.
Problem:
The right-aligned tag "pseudo-heading" layout mushes together with the
left-aligned text. This is especially messy in a narrow viewport.
Solution:
Put a `<br>` on it. This is a hack until tree-sitter-vimdoc recognizes
these pseudo-headings.
Problem:
It has long been a convention that references to the builtin terminal UI
should mention "tui", not "term", in order to avoid ambiguity vs the
builtin `:terminal` feature. The final step was to rename term.txt;
let's that step.
Solution:
- rename term.txt => tui.txt
- rename nvim_terminal_emulator.txt => terminal.txt
- `gen_help_html.lua`: generate redirects for renamed pages.
**Problem:** `vim.treesitter.get_parser` will throw an error if no parser
can be found.
- This means the caller is responsible for wrapping it in a `pcall`,
which is easy to forget
- It also makes it slightly harder to potentially memoize `get_parser`
in the future
- It's a bit unintuitive since many other `get_*` style functions
conventionally return `nil` if no object is found (e.g. `get_node`,
`get_lang`, `query.get`, etc.)
**Solution:** Return `nil` if no parser can be found or created
- This requires a function signature change, and some new assertions in
places where the parser will always (or should always) be found.
- This commit starts by making this change internally, since it is
breaking. Eventually it will be rolled out to the public API.
Problem:
The headings and help tags overlap when browsing the docs in neovim.io/doc/user/ from a mobile phone.
Solution:
Apply the correct CSS rules so that the headings and help tags wrap
nicely below one another.
Problem:
Not using minified version of bootstrap.
Don't need to load normalize with new version of bootstrap.
See https://github.com/neovim/neovim.github.io/pull/350
Solution:
Update link to bootstrap file.
Remove link to normalize.
`vim.health` is not a "plugin" but part of our Lua API and the
documentation should reflect that. This also helps make the
documentation maintenance easier as it is now generated.
Problem:
'modeline' and 'note' are unhandled in the online HTML documentation.
Some (not all) modelines are parsed by the vimdoc parser as a node of
type 'modeline'.
Solution:
- Ignore 'modeline' in HTML rendering.
- Render 'note' text in boldface.
Problem:
- Since #28678, pre-formatted text in the online documentation do not
render whitespaces correctly: should be pre-like text, but shown like
normal paragraph (see #28754).
- Code blocks with long lines should not be wrapped (e.g. see
|dev-vimpatch-list-management|).
Solution:
- Use `white-space: pre-wrap`. Compared to `white-space: pre`, this
option will make long lines including a very long URL wrapped.
This properly fixes#28754 and #28678.
- Use horizontal scrollbar for the code blocks that are horizontally too
long, instead of wrapping text. This will make the code easy to read
while the pre-text block not interfering with the navigation bar.
Problem:
On the page: https://neovim.io/doc/user/dev_vimpatch.html
The links extend beyond the container and thus end up behind the navigation to the right.
Solution:
Add these lines to get_help_html.lua:
white-space: normal;
word-wrap: break-word;
- Added `@inlinedoc` so single use Lua types can be inlined into the
functions docs. E.g.
```lua
--- @class myopts
--- @inlinedoc
---
--- Documentation for some field
--- @field somefield integer
--- @param opts myOpts
function foo(opts)
end
```
Will be rendered as
```
foo(opts)
Parameters:
- {opts} (table) Object with the fields:
- somefield (integer) Documentation
for some field
```
- Marked many classes with with `@nodoc` or `(private)`.
We can eventually introduce these when we want to.
- Add type annotations, fix most of the type warnings.
- Fix a minor bug on `spell_ignore_files`: nil error when an invalid
spelling is found but the file is not ignored.
Summary: Separate the lint job (`make lintdoc`) to validate runtime/doc,
it is no longer as a part of functionaltest (help_spec).
Build (cmake) and CI:
- `make lintdoc`: validate vimdoc files and test-generate HTML docs.
CI will run this as a part of the "docs" workflow.
- `scripts/lintdoc.lua` is added as an entry point (executable script)
for validating vimdoc files.
scripts/gen_help_html.lua:
- Move the tests for validating docs and generating HTMLs from
`help_spec.lua` to `gen_help_html`. Added:
- `gen_help_html.run_validate()`.
- `gen_help_html.test_gen()`.
- Do not hard-code `help_dir` to `build/runtime/doc`, but resolve from
`$VIMRUNTIME`. Therefore, the `make lintdoc` job will check doc files
on `./runtime/doc`, not on `./build/runtime/doc`.
- Add type annotations for gen_help_html.
There is no reason for this file to be in project root, which is crowded
as is. This also fits nicely part of the ongoing work towards gathering
as much of the documentation as possible into one place.
Problem: Wiki contents are not discoverable and hard to maintain.
Solution: Move FAQ to runtime docs.
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Problem:
We don't enable stylua for many Lua scripts. Automating code-style is an
important tool for reducing time spent on accidental (non-essential)
complexity.
Solution:
- Enable lintlua for `scripts/` directory.
- Specify `call_parentheses = "Input"`, we should allow kwargs-style
function invocations.
Problem:
In the generated docs HTML there is too much whitespace before/after `<pre>`
blocks.
- In the old layout (fixed-width), all text in `.old-help-para` is formatted as
`white-space:pre`.
- In the new layout, when `<pre>` is at the end of a `<div>`, the margins of
both are redundant, causing too much space.
Solution:
- In the old layout, always remove `<pre>` margin.
- In the new layout, disable `<pre>` margin if it is the last child.
Enforce consistent terminology (defined in
`gen_help_html.lua:spell_dict`) for common misspellings.
This does not spellcheck English in general (perhaps a future TODO,
though it may be noisy).
- quickstart
- mark lsp.txt as `new_layout`
- remove lsp-handler documentation for notifications: they don't have
handlers because they don't have server responses.
Problem:
Selecting a search result from the Algolia Docsearch widget does not
navigate to a page anchor. The docs HTML provides `<a name=…>` anchors
_near_ the `<h1>`/`<h2>`/… headings, but Algolia Docsearch expects the
anchors to be _defined on_ the headings. That's also "semantically"
nicer. https://docsearch.algolia.com/docs/manage-your-crawls/
Solution:
Set `id` on the heading element instead of placing `<a name=…>` nearby.
related: 3913ebbfcd#23839
* feat(lua): vim.tbl_contains supports general tables and predicates
Problem: `vim.tbl_contains` only works for list-like tables (integer
keys without gaps) and primitive values (in particular, not for nested
tables).
Solution: Rename `vim.tbl_contains` to `vim.list_contains` and add new
`vim.tbl_contains` that works for general tables and optionally allows
`value` to be a predicate function that is checked for every key.
