Commit Graph

56 Commits

Author SHA1 Message Date
Justin M. Keyes
668b5fc155
docs: nvim.appdata.xml, set faq to "flow" layout #28769 2024-05-16 01:53:33 -07:00
Jongwook Choi
174da7fe68 docs(gen_help_html.lua): fix broken pre text, and handle linewrap
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.
2024-05-16 09:01:05 +02:00
Justin M. Keyes
01b6bff7e9 docs: news
Set dev_xx.txt help files to use "flow" layout.
2024-05-15 23:19:26 +02:00
gusain71
ebba7ae095
docs(gen_help_html.lua): wrap legacy help at word-boundary #28678
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;
2024-05-14 04:23:43 -07:00
Justin M. Keyes
cb24a3907c
docs: format vim_diff.txt for "flow" layout #28584 2024-04-30 09:37:45 -07:00
Lewis Russell
a5fe8f59d9 docs: improve/add documentation of Lua types
- 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.
2024-03-01 23:02:18 +00:00
Jongwook Choi
be5cf33836
fix(gen_help_html): type warnings, spell_ignore_files #27254
- 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.
2024-01-29 11:02:10 -08:00
Jongwook Choi
5b1b765610
docs: enforce "treesitter" spelling #27110
It's the "tree-sitter" project, but "treesitter" in our code and docs.
2024-01-28 17:53:14 -08:00
Jongwook Choi
01e82eba20
build(docs): separate lint job to validate vimdoc #27227
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.
2024-01-28 14:22:39 -08:00
altermo
5aa14e1231
fix(lua): return after assert returns assert message (#27064) 2024-01-17 13:34:25 -06:00
dundargoc
31d7007bf7 docs: convert BACKERS.md to backers.txt
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.
2023-12-28 22:41:01 +01:00
dundargoc
ef58ee48f4
docs: add wiki FAQ to the runtime documentation (#26539)
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>
2023-12-13 17:31:39 +01:00
Justin M. Keyes
517f0cc634
build: enable lintlua for scripts/ dir #26391
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.
2023-12-04 12:38:31 -08:00
Justin M. Keyes
1a4db51d06
Revert "docs: adjust help-tag-right CSS for HTML" #26046
The style change is mostly a regression.

Reverts #25858 d50274812b
2023-11-14 09:55:54 -08:00
rsynnest
d50274812b
docs: adjust help-tag-right CSS for HTML #25858 2023-11-14 09:33:18 -08:00
dundargoc
5a2543c159
docs: small fixes (#25831)
Co-authored-by: Peter Aronoff <peter@aronoff.org>
2023-11-03 07:22:02 +08:00
Sergey Slipchenko
bc67cf3ccd
feat(gen_help_html): add anchors to help tags #25112
Fixes #21911

Co-authored by: wispl
2023-09-12 04:51:38 -07:00
zeertzjq
ca9f4a7cb1
docs: also change "vimL" and "viml" to "Vimscript" (#24414) 2023-07-21 16:30:05 +08:00
Justin M. Keyes
0a90e4b05a fix(docs): match DocSearch style with site theme
ref 2b4f9e4780
2023-07-08 16:06:46 +02:00
Justin M. Keyes
6da110d617
docs(gen_help_html): accept "~/" in file/dir params #24240 2023-07-03 05:04:43 -07:00
Justin M. Keyes
ab65a98adb
fix(docs): ignore_invalid #24174
Regex bug in scripts/gen_help_html.lua:ignore_invalid()
2023-06-27 10:21:27 -07:00
Justin M. Keyes
957d05d16b
fix(docs): too much whitespace around <pre> blocks #24151
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.
2023-06-25 12:29:56 -07:00
Justin M. Keyes
036da0d079 fix(docs): vimdoc syntax errors
gen_help_html: truncate parse-error sample text
2023-06-25 17:14:28 +02:00
Justin M. Keyes
4e6356559c
test: spellcheck :help (vimdoc) files #24109
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).
2023-06-22 03:44:51 -07:00
Justin M. Keyes
b0cf9c5fee feat(gen_help_html): ignore pi_netrw.txt errors
IDGAF about netrw
2023-06-22 10:18:24 +02:00
Justin M. Keyes
81d8fce8f9 feat(gen_help_html): non-default vimdoc.so parser
Callers can specify a non-default vimdoc.so file path.
2023-06-22 10:18:24 +02:00
Justin M. Keyes
5c73b1bb4c docs: lsp, vim_diff
- 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.
2023-06-22 10:18:17 +02:00
Justin M. Keyes
72a6643b13
docs #24061
- nvim requires rpc responses in reverse order. https://github.com/neovim/neovim/issues/19932
- NVIM_APPNAME: UIs normally should NOT set this.

ref #23520
fix #24050
fix #23660
fix #23353
fix #23337
fix #22213
fix #19161
fix #18088
fix #20693
2023-06-19 08:40:33 -07:00
Justin M. Keyes
36fd2fcaae
docs(html): define anchors for search engine #23879
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
2023-06-02 02:45:23 -07:00
Justin M. Keyes
3913ebbfcd
docs(html): algolia docsearch #23839
Need to manually include this in the generated docs html because it
doesn't use the website's (jekyll) layout template.

Maintenance notes:
https://github.com/neovim/neovim.github.io/#maintenance

Related: ce9aef12eb
2023-05-30 17:32:38 -07:00
Christian Clason
bfb19a110d
docs(html): right-align inline tags (#23403) 2023-05-02 09:45:44 +02:00
Christian Clason
4d04feb662
feat(lua): vim.tbl_contains supports general tables and predicates (#23040)
* 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.
2023-04-14 10:39:57 +02:00
Christian Clason
d7f7450017 refactor(treesitter)!: rename help parser to vimdoc 2023-04-01 15:07:16 +02:00
Ching Pei Yang
ef89f9fd46
docs: treesitter.add_directive, add_predicate #21206 2023-01-16 04:39:19 -08:00
Chris DeLuca
1bd6e4469b
docs(website): soft wrap code blocks #21644
Use `white-space: pre-wrap` to preserve white space as per `pre`, but to
allow line wrapping if the display runs out of horizontal space.

This prevents lines overflowing their box, and causing horizontal
scrolling across the entire page on small screens.

This `pre-wrap` technique is used by GitHub to format code for mobile.

See https://developer.mozilla.org/en-US/docs/Web/CSS/white-space#pre-wrap
2023-01-04 07:15:08 -08:00
Lewis Russell
5841a97500
feat!: remove hardcopy
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
2023-01-03 10:07:43 +00:00
Justin M. Keyes
1c324cb192
docs #20986
- https://github.com/neovim/tree-sitter-vimdoc v1.2.4 eliminates most
  errors in pi_netrw.txt, so we can remove that workaround from
  ignore_parse_error().
- improved codeblock
2022-12-11 18:41:26 -08:00
Dave Lage
ea39fc2cad
docs: dark/light color/accessibilty pass for generated html docs #21345 2022-12-08 14:00:18 -08:00
Christian Clason
9e1187e489 feat(web): syntax highlighting via highlight.js
download from https://highlightjs.org/download/
place `highlight/` directory next to `css/`

style needs adapting for Neovim colors
2022-12-02 16:05:00 +01:00
Christian Clason
5093f38c9f feat(help): highlighted codeblocks 2022-11-29 13:32:46 +01:00
Justin M. Keyes
24c9561a68
vim-patch: bump VIM_VERSION from 8.0 => 8.1 #20762
There are 6 remaining 8.0.x patches, tracked in:
https://github.com/neovim/neovim/issues/5431
2022-10-21 03:56:09 -07:00
Justin M. Keyes
e6917306f6
docs: update vimdoc parser #20747
Remove the user-manual ToC from help.txt, because:
1. it duplicates usr_toc.txt
2. it is not what most readers are looking for in the main help page.

fix https://github.com/neovim/tree-sitter-vimdoc/issues/49
fix https://github.com/neovim/tree-sitter-vimdoc/issues/50
fix https://github.com/neovim/tree-sitter-vimdoc/issues/51
2022-10-20 06:20:02 -07:00
Yee Cheng Chin
10ab7489eb
fix(docs-html): misaligned tabs after conceal #20690
Problem:
`gen_help_html.lua` does not properly handle tab characters after
"concealed" text (tags, taglinks, codespans). This causes misaligned
layout in "old" (preformatted) docs.

For text like `*tag*`, |tag_link|, and `code_span`, Vim hides the "*",
"|", "`" characters, but Vim still counts those characters for "virtual
column" when a tab character follows it. So if you have a tag of say
6 characters long, those two concealed character would lead to the tab
character after it start at column 8. gen_help_html.lua doesn't account
for that which leads to formatting flaws in the generated output.

Solution:
Add two spaces after concealed nodes that are followed by a tab char.
2022-10-20 03:22:46 -07:00
Justin M. Keyes
ef4c339fb9
feat(docs): update parser, HTML gen #20720
Note: although the tolerance in help_spec.lua increased, the actual
error count with the new parser decreased by about 20%. The difference
is that the old ignore_parse_error() ignored many more errors with the
old parser.

fix https://github.com/neovim/tree-sitter-vimdoc/issues/37
fix https://github.com/neovim/tree-sitter-vimdoc/issues/44
fix https://github.com/neovim/tree-sitter-vimdoc/issues/47
2022-10-18 07:18:44 -07:00
Justin M. Keyes
e5cb3104d0
docs: fix/remove invalid URLs #20647 2022-10-14 08:01:13 -07:00
Justin M. Keyes
6b01e9bf87 feat(docs-html): try to use tags for ToC headings
Problem:
The generated ToC (table of contents) uses anchors derived from the
heading title, e.g. the "Global Plugins" heading yields:
https://neovim.io/doc/user/usr_05.html#_global-plugins-
so if the heading title changes, then the old URL (anchor) is broken.

Solution:
:help tags change less often than heading titles, so if a heading
contains a *tag*, use that as its anchor name instead. Example:
https://neovim.io/doc/user/usr_05.html#standard-plugin
2022-10-10 01:05:18 +02:00
Justin M. Keyes
a7a83bc4c2 fix(docs-html): update parser
- Improve generated HTML by updating parser which includes fixes for
  single "'" and single "|":
  https://github.com/neovim/tree-sitter-vimdoc/pull/31
- Updated parser also fixes the conceal issue for "help" highlight
  queries https://github.com/neovim/tree-sitter-vimdoc/issues/23 by
  NOT including whitespace in nodes.
  - But this means we need to restore the getws() function which scrapes
    leading whitespace from the original input (buffer).
2022-10-10 01:05:18 +02:00
Justin M. Keyes
09dffb9db7
docs: various #12823
- increase python line-length limit from 88 => 100.
- gen_help_html: fix bug in "tag" case (tbl_count => tbl_contains)

ref #15632
fix #18215
fix #18479
fix #20527
fix #20532

Co-authored-by: Ben Weedon <ben@weedon.email>
2022-10-09 05:21:52 -07:00
Christian Clason
93117b3587
docs(news): add news.txt and link from README (#20426) 2022-10-08 17:49:09 +02:00
Justin M. Keyes
f7b175e049
fix(docs-html): keycodes, taglinks, column_heading #20498
Problem:
- Docs HTML: "foo ~" headings (column_heading) are not aligned with
  their table columns/contents because the leading whitespace is not
  emitted.
- taglinks starting with hyphen like |-x| were not recognized.
- keycodes like `<foo>` and `CTRL-x` were not recognized.
- ToC is not scrollable.

Solution:
- Add ws() to the column_heading case.
- Update help parser to latest version
  - supports `keycode`
  - fixes for taglink, argument
- Update .toc CSS. https://github.com/neovim/neovim.github.io/issues/297

fix https://github.com/neovim/neovim.github.io/issues/297
2022-10-06 06:16:00 -07:00