Add lamdas for docs

[monicataina]

When I am generating doc files using OpenAPI, sometimes tags like summaries or descriptions contain text that won't look so pretty in md files (e.g. generates common Markdown mistakes like the ones explained here: https://gist.github.com/DavidAnson/006a6c2a2d9d7b21b025)

The best way to see the difference is by trying a specification file that will have tags like this:

...
   description: >
        This is an example with a long description
        on multiple lines. It might not look good if the mustache
        templates will get this content as it is.
        <br>This tag won't be recognized as a standard for Markdown, so in a md file 
         this tag won't be changed into a new line.
         #Markdown rules say that you should have one blank line before and after this title




        Too many blank lines will look bad in the documentation.
   summary: A description that is written on
        multiple lines won't look so good in case we put it into a table.
...

In the mustache templates these contents won't look so good if we use simply {{description}} and {{summary}}.

Any generation that enables docs: --global-property apiDocs=true --global-property modelDocs=true

My suggestion is to use new lambda mustache templates:

1. TidyLambda for the following changes :

• Replace and normalize all non-standard apostrophes
• Replace and normalize all non-standard quotes
• Replace all HTML break tags with new lines
• Escape all opening/closing brackets
• Normalize spaces
• Normalize new lines (maximum 2 consecutive line breaks)
• Remove new lines at the end

2. MakeSingleLineLambda for the following changes:

• Convert any line breaks into a space

For these, I have a solution here: And in mustache templates, you can use them as follows:

...
Here is a better version of our description example: 

{{#lambda.tidy}}{{description}}{{/lambda.tidy}}

Here is a way to show our summary example in one line:

{{#lambda.make-single-line}}{{summary}}{{/lambda.make-single-line}}
...

It's important to note that these lambdas are optional. This means that the suggested change won't cause any issues.

PR checklist

• [x] Read the contribution guidelines.
• [x] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• [x] Run the following to build the project and update samples:

  ./mvnw clean package 
  ./bin/generate-samples.sh ./bin/configs/*.yaml
  ./bin/utils/export_docs_generators.sh
  

  (For Windows users, please run the script in Git BASH) Commit all changed files. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*. IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• [x] File the PR against the correct branch: master (upcoming 7.1.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• [x] If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

[wing328]

thanks for the PR. can we add some tests?

e.g. https://github.com/OpenAPITools/openapi-generator/tree/d0ed25a06dda4c2adff5b04d430583b276f454f8/modules/openapi-generator/src/test/java/org/openapitools/codegen/templating/mustache

[monicataina]

Certainly, @wing328. Thank you for pointing me to those similar tests. I will include them in my initial pull request and may make some minor adjustments. Would it be okay if I return with the updated pull request at the beginning of next week?

[wing328]

sure :)

thanks for the PR again

[monicataina]

Hi, @wing328. I updated my branch adding tests.

For Tidy lambda, I added a parameter to specify if you need it for docs or another purpose (e.g. for code comments).

For docs, you can use #lambda.tidyForDocs and it covers the following:

• Use maximum 2 consecutive line breaks
• Default behavior for opening/closing brackets (using its entity html code)
• All non-standard apostrophes are normalized, excluding ``` which is used for code blocks

For non-docs, you can use #lambda.tidy and it covers the following:

• Use maximum 1 consecutive line breaks (so no empty lines)
• Escape the opening/closing brackets
• All non-standard apostrophes are normalized (no exceptions)

Additionally, for both tidyForDocs and tidy, the text is converted following these rules:

• Replace starting/ending apostrophes with simple ones
• Replace all HTML break tags (
  ) by new lines
• Replace hard tabs with space
• Normalize spaces (list indentation and list style are not covered by this Lambda class)
• Make sure that a line only with ' ***' or ' ---' or ' ___' is considered an horizontal rule so it should have \r\n\r\n before and after it
• Remove new-lines at the beginning
• Remove new-lines, spaces, and tabs at the end
• Remove trailing spaces at the end of each line

For make single line lambda, there are no many changes, only that I fixed to not convert the literal "?" into space.