Lsp-mode: [Documentation] Combine custom language server docs with generated docs

[jarivm]

Currently most language docs are automatically generated. Some, however are custom made and have to be updated manually (see the list below).

Proposal
It would be nice if the documentation supported a custom section, with generated documentation filled in. This would combine the generated documentation with the manually written documentation.

Benefits

• Automation ensures the functions and variables in the docs are up to date.
• Human error can be prevented.
• Documentation will be more complete and won't have missing parts, like the Rust language documenation, which does not document every option.

List of custom language documentation

• https://github.com/emacs-lsp/lsp-mode/blob/master/docs/page/lsp-latex.md
• https://github.com/emacs-lsp/lsp-mode/blob/master/docs/page/lsp-org.md
• https://github.com/emacs-lsp/lsp-mode/blob/master/docs/page/lsp-rust.md

[yyoncho]

Sounds good. What is your proposal, having placeholder(s) in the custom language documentation and populating them from the automatic one?

@ericdallo , any thoughts?

[ericdallo]

Yeah, some placeholder would be a solution, but I'm not sure if it's trivial, I think I can take a look at this weekend :)

[jarivm]

What is your proposal, having placeholder(s) in the custom language documentation and populating them from the automatic one?

Yes, this is what I had in mind. Right now there are two templates. I propose combining these two into one, resulting in a template like this:

{{full-name}}
==========

## Server

{{documenation}} <!-- This is custom documenation, grabbed from a different markdown file. -->

For more information about the LSP server, check the [{{server-name}}]({{server-url}}).

## Installation

{{installation}}{{installation-url}}

### Debugger: {{debugger}}

## Available configurations

<generated documentation here>   

This template is then used by the generation script as usual, and the custom documentation is placed on the spot it is used at!

WDYT?

[yyoncho]

Looks good to me. I would put the debugger and configuration installation section above the documentation section.

[jarivm]

Looks good to me. I would put the debugger and configuration installation section above the documentation section.

Agreed.

[yyoncho]

@jarivm are you going to work on that? (I am asking in order to avoid collisions)

[jarivm]

@yyoncho I thought @ericdallo would take a look at it this weekend, so I am not going to work on it. @ericdallo can you confirm this? Otherwise I will work on it next week :)

[ericdallo]

Yes! it's done here: https://github.com/emacs-lsp/lsp-mode/pull/2346
Today it's a holiday in my country so I got some time to code that :)