v2.0.0 error - Githubissues

mcchrish commented 3 years ago

Getting an error:

Error running filter scripts/include-files.lua:
scripts/include-files.lua: openBinaryFile: does not exist (No such file or directory)

Using main works fine.

kdheepak commented 3 years ago

That's odd. The v2.0.0 tag didn't have the include-files feature. I wonder why you are getting that error.

Anyway, I just made a new release: https://github.com/kdheepak/panvimdoc/releases/tag/v2.1.0. This should resolve the issue :)

kdheepak commented 3 years ago

If you choose to use it for any of your plugins ( I'm a fan of your no colorschemes repo and the nnn.vim plugin btw :) ), and have feedback about the specification I'd be open to hearing what you think, or adding new features. And if you'd like to link your repo in the README, feel free to submit a PR!

mcchrish commented 3 years ago

Hi @kdheepak thanks for the quick response, v2.1.0 works perfectly.

Thank you for making this library! It's very useful for plugin dev. There are some that I think will make it even better:

Ability to skip sections/part. There are parts in the readme that does not make sense to include in the docs such as screenshots. Maybe possible to use something like  ?
Subheader does not show up in TOC
Make links order deterministic. Seems to randomly change every run. e.g. https://github.com/mcchrish/zenbones.nvim/commit/028d75f12d72e0d5534b5e60ede1bb174f8639af
Add helptag to {docname}.txt. e.g. *zenbones.txt* For NVIM v0.5.0...
Option to skip link section generation

kdheepak commented 3 years ago

Thanks! All of those are great suggestions! I’ll work on them.

mcchrish commented 3 years ago

I've been thinking of some more ideas that I hope you can consider:

Option to inline links instead of being gather in a links-section. Example:

This option will generate a helptag. When someone tries to :h gitsigns, it goes to the zenbones docs instead of the actual gitsigns doc which is not ideal.

Links                                                         *zenbones-links*

- *gitsigns*                        https://github.com/lewis6991/gitsigns.nvim

vs inline:

OTHER PLUGINS SUPPORT                         *zenbones-other-plugins-support*

Aside from LSP and basic Tree-sitter support, there are only a few plugins that
are currently supported. Please feel free to open a PR to support your favorite
plugins.

- gitsigns (https://github.com/lewis6991/gitsigns.nvim)

Kind of related above. Generate a vimdoc link if the url is pointing to the online neovim (or vim) doc. Example:

See also [cursorcolumn](https://neovim.io/doc/user/options.html#'cursorcolumn').

This will generate:

See also |'cursorcolumn'|.

kdheepak commented 3 years ago

Can you clarify what you mean when you suggest inline?

I could prefix the project name for all links, so they'd look like the following:

==============================================================================
Links                                                        *panvimdoc-links*

1. *panvimdoc-pandoc-markdown*: https://pandoc.org/MANUAL.html
2. *panvimdoc-mjlbach/babelfish.nvim*: https://github.com/mjlbach/babelfish.nvim
3. *panvimdoc-wincent/docvim*: https://github.com/wincent/docvim
4. *panvimdoc-FooSoft/md2vim*: https://github.com/FooSoft/md2vim
5. *panvimdoc-panvimdoc.md*: ./doc/panvimdoc.md
6. *panvimdoc-panvimdoc.txt*: ./doc/panvimdoc.txt
7. *panvimdoc-panvimdoc.lua*: ./scripts/panvimdoc.lua
8. *panvimdoc-entrypoint.sh*: ./entrypoint.sh
9. *panvimdoc-kdheepak/panvimdoc*: ./.github/workflows/panvimdoc.yml
10. *panvimdoc-doc/panvimdoc.txt*: ./doc/panvimdoc.txt
11. *panvimdoc-kdheepak/tabline.nvim*: https://github.com/kdheepak/tabline.nvim/blob/main/.github/workflows/ci.yml
12. *panvimdoc-doc/tabline.txt*: https://github.com/kdheepak/tabline.nvim/blob/main/doc/tabline.txt

What do you think?

mcchrish commented 3 years ago

Let's say I write a markdown like this:

Check out [gitsigns](https://github.com/lewis6991/gitsigns.nvim).

This will generate the docs like so:

Check out |gitsigns|.

==============================================================================
Links                                                        *panvimdoc-links*

1. *gitsigns*: https://github.com/lewis6991/gitsigns.nvim

Now what I mean by inline is the doc generated will look like this:

Check out gitsigns (https://github.com/lewis6991/gitsigns.nvim).

So instead of creating a link section, it will just output the url beside the text and wrap it with (). The benefit of this is that there is no need to create a tag.

Take for example on zenbones where it creates a tag for the plugin support:

Source: https://github.com/mcchrish/zenbones.nvim/blob/main/README.md#other-plugins-support Output: https://github.com/mcchrish/zenbones.nvim/blob/028d75f12d72e0d5534b5e60ede1bb174f8639af/doc/zenbones.txt#L188-L201

It's not ideal because when some tries to view a doc :h sneak, it will lead them to zenbones doc instead of the sneak.

Not 100% sure with prefixing since it might mess with the context. e.g.:

Check out |panvimdoc-gitsigns|.

kdheepak commented 3 years ago

v2.2.0 has been released. It has

the ability to skip sections/part
subheaders in TOC
deterministic link order
fixed link in plugin / project name
Auto link from neovim documentation to built in vim documentation
And different format for the autogenerated links section.

You can check out the source here: https://github.com/kdheepak/panvimdoc/blob/main/doc/panvimdoc.md and generated document here: https://github.com/kdheepak/panvimdoc/blob/main/doc/panvimdoc.txt.

mcchrish commented 3 years ago

Woah so fast! I'll check it out.

Edit: Just tested it and works great! https://github.com/mcchrish/zenbones.nvim/commit/31d28d6f812c8197688ca8c4456bc62efafa5ecf

kdheepak commented 3 years ago

I think I agree with the link changes you suggested. The latest commit on main does inline links only and gets rid of the Links autogenerated section. I'll make a new release with that now.

kdheepak commented 3 years ago

v2.3.0 published: https://github.com/kdheepak/panvimdoc/releases/tag/v2.3.0. Can you try this out?

mcchrish commented 3 years ago

I'll try that out next, but a couple of things from 2.2.0:

The skipped section seems to have some things left: https://github.com/mcchrish/zenbones.nvim/blob/4a20ee48fd8f5d6820d85bebd8b3ea4650b325f0/doc/zenbones.txt#L79-L119
When linking to a online doc, I think you should not wrap the link with a single quote. Instead just take the exact string and wrap with ||. For example: https://github.com/mcchrish/zenbones.nvim/blob/main/doc/zenbones.txt#L18. It should be |colorscheme|, not |'colorscheme'|. And for https://neovim.io/doc/user/options.html#'cursorcolumn', the output should look like this: |'cursorcolumn'|.

kdheepak commented 3 years ago

Thanks for reporting! Fixed in https://github.com/kdheepak/panvimdoc/releases/tag/v2.3.1.

mcchrish commented 3 years ago

2.3.1 works great! just one hiccup. It seems the skip is replaced by empty lines instead of being completely gone. See https://github.com/mcchrish/zenbones.nvim/commit/75d4fcd5da60da17db513c4eefb2a0de288e8074

Another idea, how about adding a credits at the bottom like This doc is generated by panvimdoc.. Sounds reasonable.

kdheepak commented 3 years ago

Another idea, how about adding a credits at the bottom like This doc is generated by panvimdoc.. Sounds reasonable.

I feel like you read my mind :) I just added it here:

https://github.com/kdheepak/panvimdoc/commit/837007914f1b94dae8cb14e1fb01a40e50d41739#diff-fa8a84af281c5508c39ec26b13da350296836c471a82385610e1b5f00f59540fR157

It seems the skip is replaced by empty lines instead of being completely gone.

Yeah, I noticed this but I wasn't able to figure out how to get rid of them. I'll have to explore again another day. I'll open a separate issue to track that.

kdheepak commented 3 years ago

Thanks for all the discussion and feedback! I just made a v2.3.2 release.

Feel free to open new issues if you want any new features or want to discuss the specification for this.

kdheepak commented 3 years ago

v2.3.3 released and it fixes the empty new lines in ignored sections: https://github.com/kdheepak/panvimdoc/commit/5ea5380a3421df587863ea9c3686ddf240e82e79

kdheepak commented 3 years ago

I wasn't a fan of how heading level 3 headers were converted to mappings always. It results in sections that look like this:

https://github.com/mcchrish/zenbones.nvim/blob/f99ccc7c50914f8fdca7b60111e2f1f5fb2850c9/doc/zenbones.txt#L113-L117

I changed it such that level 3 headers are like level 2 headers, but no tags and they are not added to the TOC.

Level 4 headers can be used for mappings.

mcchrish commented 3 years ago

Looks great: https://github.com/mcchrish/zenbones.nvim/commit/3ad37add7f69bc671b670a2055026aa2b12bc4bd

A small nitpick, the "generated by" line should have an empty line above it:

https://github.com/mcchrish/zenbones.nvim/blob/3ad37add7f69bc671b670a2055026aa2b12bc4bd/doc/zenbones.txt#L143-L147

kdheepak commented 3 years ago

Fixed in https://github.com/kdheepak/panvimdoc/commit/60cb1fcd2d6ce4ce58ffd4266957c72568cd1172, e.g. https://github.com/kdheepak/panvimdoc/commit/18bb08c83cda5e551b5bf3c72dd696bb3da120a7. And I made a new release with that change: https://github.com/kdheepak/panvimdoc/releases/tag/v2.4.1

kdheepak / panvimdoc

v2.0.0 error #4