Add a new language that automatically creates markdown documentation

[HeikoBecker]

The documentation is generated automatically for all concepts that have the MPS @doc attribute.
An example solution that shows how the language can be used is in com.mbeddr.doc.autodoc.sandbox.

For now, documentation is only created if a documentation comment is found on the root of a concept (to not clutter the reference too much). But I could also change it to include every concept or a filtering function

Checklist

• I've described my change in the CHANGELOG.md if it is visible to users of the platform (mandatory).
• I've selected the correct base branch.
• I have checked my code (edge cases, no errors) and corrected any misspellings.
• I have added comments to my code in areas where the code is hard to understand.
• I've created a new language/solution.
  • I've added the language/solution to the build script (tutorial in readme)
  • I've added a sandbox that showcases the language.
  • There is some kind of documentation available in the repository or somewhere else [e.g. MPS Platform Docs].
• I've introduced a breaking change.

[HeikoBecker]

As an illustrating example, I have added some documentation to the platform docs.

The documentationm was generated from MPS with this configuration:

[alexanderpann]

Just two 2 small findings:

• The Header4 alias is wrong.
• Please put the sandbox in the solutions folder and not the languages folder (yes, I know that is the standard setting).

All in all, the implementation looks good to me. This is probably only my personal preference and you don't have to change it, but I would stick to high level languages instead of using standard Java classes e.g. new linkedlist instead of new LinkedList, closure literal instead of Predicate etc.
The same goes for the generated nodes. Quotations + Anti quotations instead of light quotations better shows how the layout of the markdown file will look in the end.

A feature idea that I have is generating the documentation not only for concept declarations but also other declarations in the concept aspect such as interfaces, enumerations, primitive datatypes etc. and maybe also other language aspects. For that, I would recommend not using low level Open API but rather work on the node level, e.g.,:

Language l = (Language) language/com.mbeddr.doc.autodoc/.getSourceModule(); 
model structureModel = l.getStructureModelDescriptor(); 
#print structureModel.nodes(ConceptDeclaration);

The only thing that concerns me regarding the PR is that markdown as the generation target is not expressive enough to generate a nice looking documentation. The only reason why the Platform Docs look nice is that I use a lot of Markdown extensions + CSS to make it look pretty. Don't get me wrong: I like your technical approach, but I fear that the design will make people not want to read the documentation 😉
I've told you that before that I've tried (multiple times) to tackle the problem of automatically generating documentation myself in the past without mbeddr.doc, so here are some screenshots of my attempts. Attempt 1: HTML + CSS https://github.com/alexanderpann/com.github.fxlex.doc

Attempt 2: JavaDoc
https://mpsdocs.github.io/mpsDocs/MPS.Core/191.1384/org/jetbrains/mps/openapi/language/SConcept.html

There was also the related project github.com/joao-silveira/documentation-publisher-demo to generate static websites with mbeddr.doc with Markdown as the generation target.

We now have a few different solutions, and I think we should decide which approach we want to continue in the future. IMHO, generating the documentation as part of mbeddr.doc is the right approach in general, but we also have to think who the target audience of such a generated documentation is. What is the added value in comparison to the built-in documentation of the project? Can we generate meaningful, additional information that you would have to query otherwise in MPS itself that we could show? (all intentions, actions of a project, a list of deprecated concepts et.c) Maybe we can also salvage some ideas from the other projects.

[alexanderpann]

@HeikoBecker MPS has builtin support for writing and generating documentation starting from MPS 2023.3:
https://www.jetbrains.com/help/mps/documentationfacet.html#generatingdocumentation
Are you fine with me closing the PR?

[HeikoBecker]

@HeikoBecker MPS has builtin support for writing and generating documentation starting from MPS 2023.3: https://www.jetbrains.com/help/mps/documentationfacet.html#generatingdocumentation Are you fine with me closing the PR?

Yes. Onboard tools should be preferred.