[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

Author: jimschubert

.travis.yml

@@ -3,7 +3,6 @@ language: java
 jdk:
   - openjdk8
 
-
 cache:
   directories:
   - $HOME/.m2
@@ -34,6 +33,7 @@ cache:
   - $HOME/samples/server/petstore/cpp-pistache/pistache
   - $HOME/.npm  
   - $HOME/.rvm/gems/ruby-2.4.1
+  - $HOME/website/node_modules/
 
 services:
   - docker
@@ -102,6 +102,7 @@ before_install:
       gpg --keyserver keyserver.ubuntu.com --recv-key $SIGNING_KEY ;
       gpg --check-trustdb ;
     fi;
+  - pushd .; cd website; npm install; popd
 
 install:
   # Add Godeps dependencies to GOPATH and PATH
@@ -152,6 +153,15 @@ after_success:
   - if [ $DOCKER_HUB_USERNAME ]; then echo "$DOCKER_HUB_PASSWORD" | docker login --username=$DOCKER_HUB_USERNAME --password-stdin && docker build -t $DOCKER_GENERATOR_IMAGE_NAME ./modules/openapi-generator-online && if [ ! -z "$TRAVIS_TAG" ]; then docker tag $DOCKER_GENERATOR_IMAGE_NAME:latest $DOCKER_GENERATOR_IMAGE_NAME:$TRAVIS_TAG; fi && if [ ! -z "$TRAVIS_TAG" ] || [ "$TRAVIS_BRANCH" = "master" ]; then docker push $DOCKER_GENERATOR_IMAGE_NAME && echo "Pushed to $DOCKER_GENERATOR_IMAGE_NAME"; fi; fi
   ## docker: build cli image and push to Docker Hub
   - if [ $DOCKER_HUB_USERNAME ]; then echo "$DOCKER_HUB_PASSWORD" | docker login --username=$DOCKER_HUB_USERNAME --password-stdin && cp docker-entrypoint.sh ./modules/openapi-generator-cli && docker build -t $DOCKER_CODEGEN_CLI_IMAGE_NAME ./modules/openapi-generator-cli && if [ ! -z "$TRAVIS_TAG" ]; then docker tag $DOCKER_CODEGEN_CLI_IMAGE_NAME:latest $DOCKER_CODEGEN_CLI_IMAGE_NAME:$TRAVIS_TAG; fi && if [ ! -z "$TRAVIS_TAG" ] || [ "$TRAVIS_BRANCH" = "master" ]; then docker push $DOCKER_CODEGEN_CLI_IMAGE_NAME && echo "Pushed to $DOCKER_CODEGEN_CLI_IMAGE_NAME"; fi; fi
+  ## publish latest website, variables below are secure environment variables which are unavailable to PRs from forks.
+  - if [ "$TRAVIS_BRANCH" = "master" ] && [ -z $TRAVIS_TAG ] && [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
+      cd website;
+      git config --global user.name "${GH_NAME}";
+      git config --global user.email "${GH_EMAIL}";
+      echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc;
+      npm install;
+      GIT_USER="${GH_NAME}" npm run-script publish-gh-pages;
+    fi;
 
 env:
   - DOCKER_GENERATOR_IMAGE_NAME=openapitools/openapi-generator-online DOCKER_CODEGEN_CLI_IMAGE_NAME=openapitools/openapi-generator-cli NODE_ENV=test CC=gcc-5 CXX=g++-5

README.md

@@ -88,7 +88,7 @@ For old releases, please refer to the [**Release**](https://github.com/OpenAPITo
 
 ## [1.2 - Artifacts on Maven Central](#table-of-contents)
 
-You can find our released artefacts on maven central:
+You can find our released artifacts on maven central:
 
 **Core:**
 ```xml

bin/utils/copy-to-website.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+
+SCRIPT="$0"
+echo "# START SCRIPT: $SCRIPT"
+
+conduct_in=CODE_OF_CONDUCT.md
+contrib_in=CONTRIBUTING.md
+conduct_out=docs/conduct.md
+contrib_out=docs/contributing.md
+
+
+\rm -rf "${conduct_out}"
+\rm -rf "${contrib_out}"
+
+cat > "${conduct_out}" << EOF
+---
+id: code-of-conduct
+title: Code of Conduct
+---
+
+$(tail -n +3 "${conduct_in}")
+EOF
+echo "Wrote $(pwd)/${conduct_out}"
+
+cat > "${contrib_out}" << EOF
+---
+id: contributing
+title: Guidelines For Contributing
+sidebar_label: Guidelines
+---
+
+$(tail -n +3 "${contrib_in}")
+EOF
+echo "Wrote $(pwd)/${contrib_out}"

bin/utils/ensure-up-to-date

@@ -37,6 +37,9 @@ declare -a scripts=("./bin/openapi3/ruby-client-petstore.sh"
 "./bin/csharp-petstore.sh"
 "./bin/meta-codegen.sh"
 "./bin/utils/export_docs_generators.sh"
+"./bin/utils/export_generators_docusaurus_index.sh"
+"./bin/utils/copy-to-website.sh"
+"./bin/utils/export_generators_readme.sh"
 "./bin/go-petstore.sh"
 "./bin/go-gin-petstore-server.sh")
 

bin/utils/export_generator.sh

@@ -14,6 +14,4 @@ fi
 
 executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar"
 
-java -jar ${executable} config-help -g ${NAME} --named-header -o docs/generators/${NAME}.md
-
-echo "Back to the [generators list](README.md)" >> docs/generators/${NAME}.md
+java -jar ${executable} config-help -g ${NAME} --named-header --format markdown --markdown-header -o docs/generators/${NAME}.md

bin/utils/export_generators_docusaurus_index.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+
+SCRIPT="$0"
+echo "# START SCRIPT: $SCRIPT"
+
+executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar"
+
+\rm -rf docs/generators.md
+
+cat > docs/generators.md << EOF
+---
+id: generators
+title: Generators List
+---
+
+EOF
+
+java -jar $executable list --docsite >> docs/generators.md
+
+echo "Wrote $(pwd)/docs/generators.md"

bin/utils/export_generators_readme.sh

@@ -5,4 +5,16 @@ echo "# START SCRIPT: $SCRIPT"
 
 executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar"
 
-java -jar $executable list | sed -e 's/\([A-Z]*\) generators:/* \1 generators:/g' -e 's/- \([a-z0-9\-]*\)/- [\1]\(\1.md\)/g' > docs/generators/README.md
+\rm -rf docs/generators.md
+
+cat > docs/generators.md << EOF
+---
+id: generators
+title: Generators List
+---
+
+EOF
+
+java -jar $executable list | sed -e 's/\([A-Z]*\) generators:/* \1 generators:/g' -e 's/- \([a-z0-9\-]*\)/- [\1]\(generators\/\1.md\)/g' >> docs/generators.md
+
+echo "Wrote $(pwd)/docs/generators.md"

docker-compose.yml

@@ -0,0 +1,18 @@
+version: "3"
+
+services:
+  docusaurus:
+    build: .
+    ports:
+      - 3000:3000
+      - 35729:35729
+    volumes:
+      - ./docs:/app/docs
+      - ./website/blog:/app/website/blog
+      - ./website/core:/app/website/core
+      - ./website/i18n:/app/website/i18n
+      - ./website/pages:/app/website/pages
+      - ./website/static:/app/website/static
+      - ./website/sidebars.json:/app/website/sidebars.json
+      - ./website/siteConfig.js:/app/website/siteConfig.js
+    working_dir: /app/website