Improve documentation generation for models

[jougs]

Large parts of the model documentation can be generated from the model code, but this seems not to be done consistently. Thing I noticed:

• iaf_psc_alpha (and possibly some other models) still have a hand-written Parameters section, which misses the default values
• The References section should always go to the bottom of the documentation.
• The See also section should be removed in favor of a list of keywords that can either be auto-generated or supplied by the user.
• Author information is largely outdated and should go away.
• The short description at the top needs to be updated and (upon doc generation) transformed to the top level headline

[clinssen]

The See also section should be removed in favor of a list of keywords that can either be auto-generated or supplied by the user.

Isn't this exactly what the See also section is?

[jougs]

Yes and no. The See also section in the NESTML (and many NEST models for that matter) is populated with a list of related models like iaf_psc_alpha and such. However, if the NEST doc extractor sees that such a section exists, it will replace its content with links to the model directory for all tags that are listed after the doc start marker /* BeginUserDocs:. Check out the documentation of iaf_psc_alpha for an example.

I see three issues here:

• the See Also section should be removed from all model documentations in NEST and NESTML
• the doc extractor should be changed to add the section if keywords are present instead of replacing an existing one
• NESTML should provide the facilities to write down the list of keywords; things like neuron, current-based and conductance-based could probably be extracted from the AST (and maybe from the units of the incoming buffers?)

[jougs]

I still think that some additional blocks would help for this:

neuron iaf_psc_alpha:

  short_description: A leaky integrate-and-fire neuron with alpha-shaped post-synaptic currents
  keywords: integrate-and-fire, current-based
  author: The NEST Initiative

  description:
    blub
  end

  references:
    [1]
  end

  equations:
    ...