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

[jimschubert]

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 [Discussion] Generator Compatibility Check and Table #503
• List OpenAPI Specification features we support see [Discussion] Generator Compatibility Check and Table #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: [REQ] Provide templating authoring details in config-help or generate CLI command (or subcommands of generate) #1811)

[auto-labeler]

👍 Thanks for opening this issue!
🏷 I have applied any labels matching special text in your issue.

The team will review the labels and make any necessary changes.

[jimschubert]

@OpenAPITools/openapi-generator-collaborators I'm looking for feedback on this PR, which introduces a new static documentation site intended to be deployed to gh-pages. There are about 10 wiki pages to cleanup and migrate, then a couple of small things included configuring CI to automatically publish to gh-pages. But I think as-is, it is pretty sound and the TODO items can be moved to issues for later pickup.

[wing328]

@jimschubert thanks for your work on this.

Is it correct to say the documentation under wiki and "docs" folder will be consolidated into the new static documentation site and then these documentations (wiki, "docs" folder) will be removed??

[jimschubert]

@wing328 this PR adds a website directory which creates the static HTML structure and provided the markdown to HTML generation for deployment to a static HTML host (gh-pages, Netlify, etc.)

Docusaurus works from ./docs for markdown, and room React pages under the ./website directory. It combines these into the final output. Docusaurus did this, I assume, so users can still find the docs in a common location.

So the idea is to move all wiki docs under ./docs, then add these to sidebars.json so users can find the docs. Docusaurus requires a markdown headers with an id and title attribute. The id is used in sidebars.json to include that document into the structure.

[wing328]

Understood so the wiki pages will be consolidated into ./docs folder. I suggest we still keep the wiki pages by leaving a note there saying the documentation has moved to a new location as there are still many links out there referencing the wiki pages.

[jimschubert]

I think this PR is ready for evaluation, and to merge into master if we're all comfortable with it. This solution has been more maintainable than my original attempt with Git Playbook. One of the biggest differences being that Docusaurus does automatic resolution of links in referenced documentation, and compiles those docs to HTML output for deployment (Git Playbook pulled Markdown from the repo and rendered client-side, resulting in a small rendering delay).

After deployment, we'd want to clear the Wiki texts I've ticked in the TODO items, and link to the new deployed pages. The remaining TODO items can either be left on the wiki (git, repo, and core contributor specific details), or would take some time to rewrite (FAQ has many headers and makes nav look jumped, new generator wiki just links to PRs where people have created new generators).

I've updated the CI to publish to gh-pages according to the Docusaurus documentation. The only differences are that I've used npm instead of yarn for consistency with other task executions, and I've applied additional checks prior to publishing.

We currently have a CNAME for http://openapi-generator.tech/ bound to https://openapitools.github.io, and I'm not sure how the bound domain would work with the default configuration. If, after publish, the site does not render correctly, we may need to change siteConfig.js:

diff --git a/website/siteConfig.js b/website/siteConfig.js
index 2f9d548885..62a1dfd2b1 100755
--- a/website/siteConfig.js
+++ b/website/siteConfig.js
@@ -13,8 +13,8 @@ const users = loadYaml("dynamic/users.yml");
 const siteConfig = {
   title: 'OpenAPI Generator', // Title for your website.
   tagline: 'Generate clients, servers, and documentation from OpenAPI 2.0/3.x documents',
-  url: 'https://OpenAPITools.github.io', // Your website URL
-  baseUrl: '/openapi-generator/', // Base URL for your project */
+  url: 'https://openapi-generator.tech', // Your website URL
+  baseUrl: '/', // Base URL for your project */
   // For github.io type URLs, you would set the url and baseUrl like:
   //   url: 'https://facebook.github.io',
   //   baseUrl: '/test-site/',

[ackintosh]

Great job!!! Looks good to me. ✨

[ackintosh]

My thoughts about the questions:

Wiki Server Stub docs Q: Can we move the few notes and rely on users to query CLI for generation options?

I think yes, we can rely on users to query CLI for the generator options. (e.g . What the generator name is available on -g option)

If users couldn't find that, we may need to provide users how to query what parameters available.

Wiki Git Branches

I think the wiki page can be left on the Wiki as the page targets us (team members).

But users may wants to know that the release frequency in the project and what kind of changes is contained in each release.

[jimschubert]

@ackintosh Thanks for the feedback!
I did try to break the wiki stuff out as things only relevant to those of us with commit access.

The release cycle would be addressed by the remaining FAQ page. I will have to sort this FAQ into the docs in a meaningful way. There are process, generator, and general questions all answered in the same doc, and I think some of the question are clarified in the updated guides.

[wing328]

Can the following be left on the Wiki?

I think it's fine to left some docs in the wiki to start with (I didn't expect all docs to be migrated in the debut)

[jimschubert]

@wing328 thanks for the feedback. I have one more remaining doc to migrate (new generator). And one more I would like to write: extending a built-in generator (see https://github.com/jimschubert/custom-generator-example). I think the remaining wiki pages would best be left on the wiki, and the remaining TODO items would be new docs which I can create issues for tracking.

After this, I think the "Documentation" section of our short-term roadmap will be complete.

[wing328]

@jimschubert when you've time, can you please resolve the merge conflicts?

[jimschubert]

@wing328 I've fixed the merge conflicts (they're due to the new markdown formatting in the generators docs).

I've also rewrote the documentation for creating a new generator, and put this under the "Contributing" sidebar section in docs.

This completes the migration of all content from the wiki that I have planned for this branch. The remaining two items are currently undocumented and should probably become issues to document these (I think you may have already accounted for the feature matrix).

Once this is merged, and the deployment options are tweaked to work with the CNAME and custom domain, a follow up would be to modify the migrated wiki pages to point to the new "current" docs whether that's on the hosted site or a direct link to the docs within the repository. I'd also like to thin out the README and direct users to the new site as the source of truth for guides/options/etc.

Docusaurus also gives us the ability to version docs. So when we move between minor and major versions, we will probably want to execute the versioning strategy for deployment.

[wing328]

Travis CI failed with the following:

remote: Invalid username or password.
fatal: Authentication failed for 'https://[email protected]/OpenAPITools/openapi-generator.git/'
Error: Git push failed
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @ publish-gh-pages: `docusaurus-publish`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the @ publish-gh-pages script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/travis/.npm/_logs/2019-01

[wing328]

I saw GH_NAME, GH_EMAIL and GITHUB_TOKEN setup in Travis and my guess is that GH_NAME is not setup properly - should be jimschubert instead of Jim?

[jimschubert]

@wing328 yeah it should be my username. I wonder if I set it to my full name by accident. Have you changed this already?

[wing328]

Yes, just changed it 3 seconds ago with my user ID, token and email address. Just restarted the Travis latest master job to see how it goes.

[wing328]

UPDATE: Just renamed GITHUB_TOKEN to GH_TOKEN (environment variable) and restarted the job again (previous one failed)

[wing328]

Fixed (https://travis-ci.org/OpenAPITools/openapi-generator/builds/481295957)

[jimschubert]

Thanks for sorting that out! I was following two articles for CI setup, and they must have differed sightly and I missed it.

[wing328]

@jimschubert no problem bro.