Wiki Translation Repositories

Official translations of the wiki are not practical due to varying dialects, dodgy translator programs, and the increased workload needed to officially support the translations. A different approach is to have monkeys, who wish to contribute to the community, run their own translation of the wiki.

This tutorial will go into the details of how to setup a copy of the wiki on GitHub that looks and feels like the official wiki, including Travis-CI automatically converting your AsciiDoc content to HTML, then publishing those files on each commit.

You are not required to translate every page or even mirror changes to the official wiki. What is required is a linked wiki be robust enough to actually help other monkeys and that the content is kept current. If it’s deemed worthy, a link to your repository, whether its stored on your own domain or not, will be added to the main page of the wiki under the Languages topic.

Although this is a tutorial on setting up and configuring your own copy of the official wiki, you still must adhere to the jMonkeyEngine licensing.

This includes the use of a domain name that includes the jMonkeyEngine name.

Prerequisites

For this tutorial you can either setup with Git, or the Atom Editor, which uses basic GitHub commands by default. You will be loosely implementing the instructions from Steve Klabnik.

You will need to meet these requirements to continue:

The Atom editor also has a Git Plus package that uses Git if it’s already on your system. Open File  Settings and enter “git” into the search box to locate and install.

For a list of git commands, use one of these:

See also Travis-CI:

GitHub/Travis CI Setup

This topic applies to both Git and the Atom Editor. You must do this before you do anything else.

Github

  1. Create a new repository on github.com for your wiki. (NOT a fork)

    1. Enter a unique name for your repository.

  2. After your repository has been created, you will need to add a new “gh-pages” branch.

    1. This will automatically setup your repository for compiling “gh-pages”.

    2. After creating the “gh-pages” branch, from your repositories main page, click the Settings link and scroll down to the “GitHub Pages” panel for more configuration options and to see your sites new URL.

      There are two URLs you will need for configuration.

      • Your gh-pages URL: https://username.github.io/repo-name/

      • Your repository URL: https://github.com/username/repo-name

      This is how they will be referred to in this tutorial.

  3. Setup GH_TOKEN variable:

    1. You need to generate a GH_TOKEN in github.com, and set up Environment Variables in travis-ci.org or travis-ci.com, depending on whether your repository is public or not. This variable will be used in the deploy_ghpages.sh file.

    2. Describe it however you wish and then you will need to check some boxes. Check these ones:

      • public_repo

        If your repository is private, you can set repo instead.

        GitHub will create the token and show a page with the value.

        THIS IS THE ONLY TIME YOU GET TO SEE THIS SO DON’T CLICK AWAY IMMEDIATELY!

        You will need to copy this token into someplace you trust. It’ll never be shown to you after this time, so it’s important to double-check your work. You can always regenerate a new token, but then you will have to change any script or apps that use it.

Travis CI

  1. Click your name icon and select Settings  Billing  Marketplace or the “Marketplace” link at the top of the page header.

  2. Click the “Travis-CI” link. If you don’t see one listed, find it using the search box.

  3. Scroll to the bottom of the page and under “Pricing and setup” select the “Open Source” option if this is a public_repo or the payment plan of your choice.

    1. When ready, select the Install button.

    2. Click through until you are redirected to the Travis-Ci website.

  4. On Travis-CI, flick the repository switch on for your gh-pages project.

    You can’t see your project on the list? Click on the Sync account button (top right) and it should be OK.

  5. Click the cog to go to the settings tab and configure it.

    1. Check some options on General:

      1. check the Build only if .travis.yml is present option.

      2. Check the Build pushed options.

    2. Create some Environment Variables that will be used in .travis.yml file:

      1. GH_TOKEN: the token created on previous step.

        Uncheck the Display value in build log option. This is the default action.

Using Git Command Line to finish

  1. Clone the wiki or your fork of the wiki and your new repository. Cloning and pushing takes some time due to the size of the wiki. Be patient.

    $ git clone https://github.com/jMonkeyEngine/wiki.git
$ git clone https://github.com/user/repository.git
$ cd repository
$ git checkout master

  2. Copy everything from the localized wiki repository to the localized new repository, especially these files:

    1. .travis.yml

    2. build.gradle

    3. deploy_ghpages.sh

    4. gradlew

      Travis CI will execute ./gradlew asciidoctor and ./deploy_ghpages.sh after you push your commits.

      If you have ever forked the official wiki, I suggest you rename it to origin_wiki or official_wiki. Then, you can still contribute to the official wiki with that fork.

  3. Give gradlew, deploy_ghpages.sh permission to be executed. If you don’t do this, travis-ci.org will fail, due to no permission.

    git update-index --chmod=+x deploy_ghpages.sh
git update-index --chmod=+x gradlew
git push

  4. At this point you need to change the wiki specific attributes to complete the setup.

Using Atom Editor to finish

This topic assumes you have already downloaded, installed and configured the Atom Editor as well as cloned the wiki or your fork of the wiki and it’s open in the Atom Editor.

  1. In the Atom Editor, select File  New Window or Ctrl + Shift + N.

    1. Delete the new page that opens by default.

  2. In the new window, select Packages  Command Palette  Toggle or Ctrl + Shift + P.

    1. Enter “github” into the search box.

    2. Select the GitHub Clone button.

    3. Enter the URL to your repository.

    4. When ready, click the Clone button.

  3. Copy everything from the localized wiki repository to the localized new repository, especially these files:

    1. .travis.yml

    2. build.gradle

    3. deploy_ghpages.sh

    4. gradlew

  4. Give gradlew, deploy_ghpages.sh permission to be executed. If you don’t do this, travis-ci.org will fail, due to no permission.

    1. If you use Git Plus, select Packages  Git Plus  Run and enter these arguments.

      Using Git Plus
      git update-index --chmod=+x deploy_ghpages.sh
git update-index --chmod=+x gradlew
git push

    2. If you dont have Git, then edit the travis.yml file and add this after the branches: command.

      No Git Installed
      branches:
  except:
    - gh-pages
# No git, change permissions here.
before_install:
 - chmod +x deploy_ghpages.sh
 - chmod +x gradlew

  5. At this point you need to change the wiki specific attributes to complete the setup.

Changing Wiki Specific Attributes

These changes will make your copy of the wiki, including all links, 100% dependent on your gh-pages branch. You’re on your own after this point so if you want selective links to still point to the official wiki, it’s up to you to determine which.

At minimum, you still have to change the attributes “endpoint-url”, “wiki_link_edit_prefix”, and “wiki_link_create_prefix” in the “build.gradle” file.
Git CommandLine

  1. Using Git Grep or the command line editor of your choice, find and replace the following:

    1. Find the official wiki gh-pages address of https://wiki.jmonkeyengine.org.

    2. Replace it with your gh-pages address https://username.github.io/repo-name.

    3. Find the official wiki repository address of https://github.com/jMonkeyEngine/wiki.

    4. Replace it with your repository address of https://github.com/username/repo-name.

  2. Change the build status link for your repository in the README.adoc page.

    image:https://travis-ci.org/jMonkeyEngine/wiki.svg?branch=master["Build Status", link="https://travis-ci.org/jMonkeyEngine/wiki"]

  3. After you have done all the above, commit and push to your wiki repository.

Atom Editor

  1. Select Find  Find in Project or Ctrl + Shift + F.

    1. Enter the official wiki gh-pages address of https://wiki.jmonkeyengine.org into the search box and then select the Find All button.

    2. Enter your gh-pages address https://username.github.io/repo-name in the “Replace All” box and when ready, select the Replace All button.

    3. Enter the official wiki repository address of https://github.com/jMonkeyEngine/wiki into the search box and then select the Find All button.

    4. Enter your repository address of https://github.com/username/repo-name in the “Replace All” box and when ready, select the Replace All button.

  2. Change the build status link for your repository in the README.adoc page.

    image:https://travis-ci.org/jMonkeyEngine/wiki.svg?branch=master["Build Status", link="https://travis-ci.org/jMonkeyEngine/wiki"]

  3. After you have done all the above, File  Save All.

  4. Open the Git panel, Packages  GitHub  Toggle Git Tab or Ctrl + 9.

    1. Stage All.

    2. Enter a “initial commit” message.

    3. Commit and push to your wiki repository. You can see the result after a few minutes.

Conclusion

Travis should have built your copy of the wiki and moved all the .html to your “gh-pages” branch. If this didn’t happen, then something is wrong with your setup. Examine the logs of your repository from your Travis-CI account to help you troubleshoot where you went wrong. You can expand any of the command tags by clicking on them to get a more in-depth reveal of the logged info.

When you feel your repository is ready, create a thread on the forum requesting it be added to the official wiki. If approved, create a pull request of the wiki documentation page adding your repository link under the “Languages” topic.

Thanks for your interest in removing the language barrier that may prevent other monkeys from learning more about the jMonkeyEngine.