Skip to content

Commit 0b5a8c5

Browse files
kdheepakactions-user
kdheepak
authored and
actions-user
committed
Auto generate docs
1 parent 31d9973 commit 0b5a8c5

File tree

1 file changed

+156
-2
lines changed

1 file changed

+156
-2
lines changed

‎doc/panvimdoc.txt‎

Lines changed: 156 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,160 @@ Table of Contents *panvimdoc-table-of-contents*
88

99
Write documentation in |pandoc markdown|. Generate documentation in vimdoc.
1010

11+
==============================================================================
12+
2. Motivation *panvimdoc-motivation*
13+
14+
Writing documentation is hard. Writing documentation for vim plugins is an
15+
additional hassle. Making writing vim plugin documentation frictionless can be
16+
useful.
17+
18+
Writing documentation in markdown and converting it to vimdoc can help toward
19+
that goal. This way, plugin authors will have to write documentation just once
20+
as part of the README of the project, and have the vim documentation
21+
autogenerated.
22+
23+
Writing vim documentation requires conforming to a few simple rules. Although >
24+
vimdoc < is not a well defined spec, it does have some nice syntax highlighting
25+
and features like tags and links when a text file is in > vimdoc < compatible
26+
format and when the > filetype=help < in vim. Also, typically, while vim
27+
documentation is just plain text files, they are usually formatted well using
28+
whitespace. Preserving these features and characteristics is important.
29+
30+
See |References| for more information.
31+
32+
It would be nice to write documentation in Markdown and convert to vimdoc.
33+
[@mjlbach](https://github.com/mjlbach) has already implemented a neovim
34+
treesitter markdown to vimdoc converter that works fairly well. This approach
35+
is close to ideal. There are no dependencies ( except for the Markdown
36+
treesitter parser ). While it appears that the markdown parser may cause
37+
crashes, I have not experienced any in my use. It is neovim only but you can
38+
use this on github actions even for a vim plugin documentation.
39+
40+
I found two other projects that do something similar, again linked in the
41+
references. As far as I can tell, these projects are all in use and actively
42+
maintained and these projects may suit your need.
43+
44+
However, none of these projects use Pandoc. Pandoc Markdown supports a wide
45+
number of features. Most importantly, it supports a range of Markdown formats
46+
and flavors. And, Pandoc has lua filters and a custom output writer that can be
47+
configured in lua. Pandoc filters are easy to write and maintain too.
48+
49+
This project aims to write a specification in Pandoc Markdown, and take
50+
advantage of Pandoc filters, to convert a Markdown file to a vim documentation
51+
help file.
52+
53+
==============================================================================
54+
3. Goals: *panvimdoc-goals:*
55+
56+
57+
-Markdown file must be readable when the file is presented as the README on GitHub / GitLab.
58+
-Markdown file converted to HTML using Pandoc must be web friendly and render appropriately (if the user chooses to do so).
59+
-Vim documentation generated must support links and tags.
60+
-Vim documentation generated should be aesthetically pleasing to view, in vim and as a plain text file.
61+
62+
63+
-This means using column and spacing appropriately.
64+
65+
-Use built in Vim documentation as guidelines but not rules.
66+
67+
68+
==============================================================================
69+
4. Features *panvimdoc-features*
70+
71+
72+
-Autogenerate title for vim documentation
73+
-Generate links and tags
74+
-Support markdown syntax for tables
75+
-Support raw vimdoc syntax where ever needed for manual control.
76+
77+
78+
==============================================================================
79+
5. Specification *panvimdoc-specification*
80+
81+
The specification is described in |panvimdoc.md| along with examples. The
82+
generated output is in |panvimdoc.txt|. The reference implementation of the
83+
Pandoc lua filter is in |panvimdoc.lua|.
84+
85+
If you would like to contribute to the specification please feel free to
86+
comment on this issue: |https://github.com/kdheepak/panvimdoc/issues/1|.
87+
88+
==============================================================================
89+
6. Usage *panvimdoc-usage*
90+
91+
>
92+
pandoc -t scripts/panvimdoc.lua ${INPUT} ${OUTPUT}
93+
<
94+
95+
96+
The following are the metadata fields that the custom writer uses:
97+
98+
99+
->
100+
project
101+
< (String) _required_: This is typically the plugin name. This is prefixed to all generated tags
102+
->
103+
vimdoctitle
104+
< (String) _required_: This is the name of the documentation file that you want to generate
105+
->
106+
vimversion
107+
< (String) _optional_: The version vim / neovim that the plugin is targeting. If not present, the version of vim in the available environment is used.
108+
->
109+
toc
110+
< (Boolean) _optional_: Whether to generate table of contents or not
111+
112+
113+
Example:
114+
115+
>
116+
---
117+
project: panvimdoc
118+
vimdoctitle: panvimdoc.txt
119+
vimversion: Neovim v0.5.0
120+
toc: true
121+
---
122+
<
123+
124+
125+
USING GITHUB ACTIONS *panvimdoc-using-github-actions*
126+
127+
Add the following to > ./.github/workflows/pandocvim.yml <:
128+
129+
>
130+
name: panvimdoc
131+
132+
on: [push]
133+
134+
jobs:
135+
custom_test:
136+
runs-on: ubuntu-latest
137+
name: pandoc to vimdoc
138+
steps:
139+
- uses: actions/checkout@v2
140+
- name: PanVimDoc
141+
uses: kdheepak/panvimdoc@v1
142+
with:
143+
pandoc: INPUT_FILENAME.md
144+
vimdoc: doc/OUTPUT_FILENAME.txt
145+
- uses: stefanzweifel/git-auto-commit-action@v4
146+
with:
147+
commit_message: "Auto generate docs"
148+
branch: ${{ github.head_ref }}
149+
<
150+
151+
152+
Choose > INPUT_FILENAME < and > OUTPUT_FILENAME < appropriately.
153+
154+
==============================================================================
155+
7. References *panvimdoc-references*
156+
157+
158+
-|https://learnvimscriptthehardway.stevelosh.com/chapters/54.html|
159+
-|https://github.com/nanotee/vimdoc-notes|
160+
-|https://github.com/mjlbach/babelfish.nvim|
161+
-|https://foosoft.net/projects/md2vim/|
162+
-|https://github.com/wincent/docvim|
163+
164+
11165
CODEBLOCKS *panvimdoc-codeblocks*
12166

13167
>
@@ -36,7 +190,7 @@ will be rendered as below:
36190
You can use codeblocks that have language as `vimdoc` to write raw vimdoc.
37191

38192
==============================================================================
39-
2. Title *panvimdoc-title*
193+
8. Title *panvimdoc-title*
40194

41195
The first line of the documentation that is generated will look something like
42196
this:
@@ -47,7 +201,7 @@ this:
47201

48202

49203
==============================================================================
50-
3. Heading *panvimdoc-heading*
204+
9. Heading *panvimdoc-heading*
51205

52206
Main headings are numbered.
53207

0 commit comments

Comments
 (0)