Skip to content

Conversation

@jimschubert
Copy link
Member

@jimschubert jimschubert commented Oct 16, 2019

Updates CLI helpers to output docs pages and docs/generators.md so it may allow navigation on GitHub. This reintroduces work from #4120. The version of docusaurus we were on didn't index nested files correctly, so generators/ada.md wouldn't create a link to /docs/generators/ada. Part of this fix was to remove the id attribute from these files, which may increase the likelihood of id collisions in the future. I think this is acceptable if it makes the docs more easily discoverable and browsable on GitHub.

This also adds some clarification to templating.md and cutomizations.md based on some discussion in Slack over the past week. I reviewed these two documents and the confusion about whether users needed to modify mustache templates only vs creating a new custom generator was apparent after the discussions in chat. Hopefully the brief overview in templating.md and the expansion in customizations.md will reduce any further confusion.

This PR also updates docusaurus and incorporates two new features: collapsible sidebar and scroll-to-top.

PR checklist

  • Read the contribution guidelines.
  • If contributing template-only or documentation-only changes which will change sample output, build the project before .
  • Run the shell script(s) under ./bin/ (or Windows batch scripts under.\bin\windows) to update Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit, and these must match the expectations made by your contribution. You only need to run ./bin/{LANG}-petstore.sh, ./bin/openapi3/{LANG}-petstore.sh if updating the code or mustache templates for a language ({LANG}) (e.g. php, ruby, python, etc).
  • File the PR against the correct branch: master, 4.1.x, 5.0.x. Default: master.
  • Copy the technical committee to review the pull request if your PR is targeting a particular programming language.

cc @OpenAPITools/generator-core-team @wing328
cc @vitorvezani (fyi)

@jimschubert jimschubert mentioned this pull request Oct 16, 2019
4 tasks
@jimschubert jimschubert added this to the 4.2.0 milestone Oct 16, 2019
Copy link
Member

@wing328 wing328 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@jimschubert jimschubert merged commit 0e1ce6b into master Oct 16, 2019
@jimschubert jimschubert deleted the custom-template-clarifications branch October 16, 2019 22:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants