New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 20 commits into from Jan 18, 2019

Conversation

Projects
None yet
3 participants
@jimschubert
Copy link
Member

jimschubert commented Dec 28, 2018

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?

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)
@auto-labeler

This comment has been minimized.

Copy link

auto-labeler bot commented Dec 28, 2018

👍 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 added some commits Dec 28, 2018

Merge branch 'master' into docusaurus
* master: (26 commits)
  Delete unused method (#1744)
  Use JsonNullable wrapper on nullable/x-nullable fields (#1762)
  Add an option to use reflection in equals, hashCode (Java client) (#1767)
  [Slim] Encode path to support non-latin characters (#1687)
  [elm] Add support for sending headers (#1704)
  Add test case for InlineModelResolver: inline array response (#1778)
  fix group parameter logic (#1779)
  Add test case for InlineModelResolver: inline array request body (#1777)
  Add test case for InlineModelResolver: inline array schema (#1772)
  Fix type inference error (#1773)
  skip default value for contaier in spring (#1725)
  [Slim] Add PHP CodeSniffer config template (#1764)
  Use CompareNetObject for object comparison in C# client (refactor) (#1765)
  Add test case for InlineModelResolver (#1771)
  Add online gen tests (#1759)
  Resolve inline models before preprocess (#1761)
  better handling of allOf (composition) (#1757)
  Fix UUID support (#1746)
  Use appInfo.version for podspec (#1760)
  [Swift 4] Add `createURLRequest` method (#1727)
  ...
@jimschubert

This comment has been minimized.

Copy link
Member Author

jimschubert commented Dec 31, 2018

@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

This comment has been minimized.

Copy link
Member

wing328 commented Dec 31, 2018

@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

This comment has been minimized.

Copy link
Member Author

jimschubert commented Dec 31, 2018

@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

This comment has been minimized.

Copy link
Member

wing328 commented Dec 31, 2018

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.

@wing328 wing328 changed the title [feat][docs][website] Iniital docusaurus based site [feat][docs][website] Initial docusaurus based site Jan 2, 2019

@jimschubert jimschubert requested review from jmini , wing328 and ackintosh Jan 4, 2019

@jimschubert

This comment has been minimized.

Copy link
Member Author

jimschubert commented Jan 4, 2019

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
Copy link
Member

ackintosh left a comment

Great job!!! Looks good to me.

@ackintosh

This comment has been minimized.

Copy link
Member

ackintosh commented Jan 5, 2019

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

This comment has been minimized.

Copy link
Member Author

jimschubert commented Jan 6, 2019

@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.

@jimschubert jimschubert referenced this pull request Jan 6, 2019

Closed

Documentation #1614

0 of 4 tasks complete

jimschubert added some commits Jan 7, 2019

[docs] Migrate FAQ, release summary from wiki
FAQ has been split into multiple smaller documents to better categorize
and allow users to find what they're looking for (in docs folder or in
new website).

Release summary information (versioning strategy and cadence) has been
migrated from the Wiki and clarified a bit.

Also adds copy button for all code snippets in website.
@wing328

This comment has been minimized.

Copy link
Member

wing328 commented Jan 7, 2019

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

This comment has been minimized.

Copy link
Member Author

jimschubert commented Jan 7, 2019

@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

This comment has been minimized.

Copy link
Member

wing328 commented Jan 9, 2019

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

jimschubert added some commits Jan 9, 2019

Merge branch 'master' into docusaurus
* master: (52 commits)
  Support for "x-enum-descriptions" (#1752)
  add new sample files
  Add a checklist to issue report (#1851)
  Fix typo in template (#1859)
  update samples
  add isModel to updatebooleanflagwithcodegenproperty (#1844)
  [python-client] Add model default values (#1776)
  fix: force to decode as utf-8 when header contains application/json to avoid text garbling. (#1700)
  Better support for composed schema (allOf) (#1842)
  Add additional properties to Java CodegenModel (#1854)
  Minor Angular type improvements (#1843)
  [DART] fix: set fields to null if json value is null. (#1798)
  add options to maven plugin (#1845)
  fix unqiue name in handling forward slash (#1839)
  better handle of oauth (#1838)
  [C] Support for authentication methods (#1628)
  better error message when parameter ref not defined (#1837)
  Add links to articles about openapi generator
  Add a link to @watiko article
  Delete langs command (#1836)
  ...
@jimschubert

This comment has been minimized.

Copy link
Member Author

jimschubert commented Jan 9, 2019

@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 wing328 added this to the 4.0.0 milestone Jan 18, 2019

@wing328 wing328 merged commit 6fe9a52 into OpenAPITools:master Jan 18, 2019

3 of 4 checks passed

ci/circleci Your tests failed on CircleCI
Details
Shippable Run 5321 status is SUCCESS.
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@wing328

This comment has been minimized.

Copy link
Member

wing328 commented Jan 18, 2019

Travis CI failed with the following:

remote: Invalid username or password.
fatal: Authentication failed for 'https://Jim@github.com/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

This comment has been minimized.

Copy link
Member

wing328 commented Jan 18, 2019

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

This comment has been minimized.

Copy link
Member Author

jimschubert commented Jan 18, 2019

@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

This comment has been minimized.

Copy link
Member

wing328 commented Jan 18, 2019

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

This comment has been minimized.

Copy link
Member

wing328 commented Jan 18, 2019

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

@wing328

This comment has been minimized.

@jimschubert

This comment has been minimized.

Copy link
Member Author

jimschubert commented Jan 18, 2019

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

@jimschubert jimschubert deleted the jimschubert:docusaurus branch Jan 18, 2019

@wing328

This comment has been minimized.

Copy link
Member

wing328 commented Jan 18, 2019

@jimschubert no problem bro.

mvniekerk pushed a commit to GrindrodBank/openapi-generator that referenced this pull request Jan 28, 2019

[feat][docs][website] Initial docusaurus based site (OpenAPITools#1770)
* Iniital docusaurus based site

* Remove error about default local being used by String.format

* Change pinned users to represent global presence rather than alphabetical order pinning

* Include generator indexes in ensure-up-to-date (docusaurus site and /generators/README)

* Add Font Awesome attribution footer

* Remove feature callout until it is completed

* Include NPM try it out section

* Improve "Getting Started" type docs

* Include new custom template documentation

* Updating templating and customization docs

* Add vendor extension docs

* Cleanup templating page(s).

* Move users to yaml file for easy edit.

* travis configuration, and baseUrl mods to image URLs

* [docs] Migrate FAQ, release summary  from wiki

FAQ has been split into multiple smaller documents to better categorize
and allow users to find what they're looking for (in docs folder or in
new website).

Release summary information (versioning strategy and cadence) has been
migrated from the Wiki and clarified a bit.

Also adds copy button for all code snippets in website.

* Copy current contributing/code of conduct to website

* [docs] Creating a new generator
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment