Skip to content
GitLab
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
  • O openapi-generator
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 3,476
    • Issues 3,476
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 402
    • Merge requests 402
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Packages and registries
    • Packages and registries
    • Package Registry
    • Infrastructure Registry
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Repository
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • OpenAPI Tools
  • openapi-generator
  • Merge requests
  • !1770

[feat][docs][website] Initial docusaurus based site

  • Review changes

  • Download
  • Email patches
  • Plain diff
Merged Jim Schubert requested to merge github/fork/jimschubert/docusaurus into master Dec 28, 2018
  • Overview 0
  • Commits 20
  • Pipelines 0
  • Changes 196

PR checklist

  • Read the contribution guidelines.
  • Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh and ./bin/security/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\.
  • Filed the PR against the correct branch: master, 3.4.x, 4.0.x. Default: master.
  • Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

To evaluate:

cd website
yarn start

This will automatically open http://localhost:3000 with the generated site.

This PR include some changes to the docs under ./docs to support the docusaurus configuration. Every generator markdown under ./docs/generators includes the docusaurus metadata header, although the tool doesn't currently support indexing markdown documents in subdirectories under ./docs (as they support localization and walking the tree becomes difficult).

There are some todo items, either before or after this is evaluated:

  • Include bin/utils/export_generators_docusaurus_index.sh in CI
  • Update CI to deploy to GitHub Pages
  • Add attribution info for Font-awesome to footer (svgs pulled from encharm/Font-Awesome-SVG-PNG
  • Move users list to editable yaml/page in same way as team (team.yml)
  • Create an introduction guide
  • Create more tutorials for extending the generator
  • Better document openapi-generator-online
  • Feature matrix see #503
  • List OpenAPI Specification features we support see #503
  • Script out the copy of CODE_OF_CONDUCT.md and CONTRIBUTING.md from project root to docs/conduct.md and docs/contributing.md (where these include docusaurus headers.
  • Migrate Wiki FAQ
  • Migrate (or rewrite) Wiki How to add a New Generator to Extending section
  • Migrate (or incorporate into templating.md) Wiki Mustache Variables
  • Migrate Wiki Vendor Extension

Questions:

Can the following be left on the Wiki?

  • Wiki Server Stub docs Q: Can we move the few notes and rely on users to query CLI for generation options?
  • Wiki Git Branches
  • Wiki Release Checklist
  • Migrate Wiki Samples Folder Q: What does this page provide to users?
  • Migrate Wiki Pull Request Checklist to Contributing section. Q: Should this be removed as redundant with PR/Issue templates?
  • Migrate Wiki Integration Tests to contributor section

TODO items (so I don't forget)

  • Create issue to dump templating information (embeddedTemplateDir/templateDir) via config-help
  • Create issue to dump supporting files used by generator (useful for template authors)
  • Create issue to dump OpenAPI supported features per generator (included all three above items in single feature request: #1811)
Assignee
Assign to
Reviewers
Request review from
Time tracking
Source branch: github/fork/jimschubert/docusaurus