dong-bellevue / wiki

a wiki for jMonkeyEngine

jMonkeyEngine Documentation

see https://jmonkeyengine.github.io/wiki/documentation

The project to store, edit, and generate the documentation of jMonkeyEngine.

The documentation ([src/docs/asciidoc]) is editable :

• online via github (Edit button located at top of the Wiki page + Pull Request)

• offline with Netbeans after local git clone + open

• offline with Atom editor, see Atom Editor for Wiki Editing

Prerequisites

1. Have a GitHub account.

2. Optional: Are a Wiki project member.

If you are not a member, you can fork the repository into your GitHub account and issue pull requests from there or online via github. (Edit button located at top of the Wiki page + Pull Request)

To fork the Wiki repository into your GitHub Account:

• In the menu at the top of the page, select the Fork button.

The syntax is asciidoc :

• Asciidoc Syntax Quick Reference

• Asciidoctor User Manual

An easy to use primer for GitHub commands can be found here:

• git - the simple guide

Contribute

There are a few simple rules to follow when contributing.

1. It’s not required but it’s a good idea to give a heads up you made a P/R on the jMonkeyEngine Forum under the Documentation topic.

2. When adding documents, make sure to always complete the header of your document first.

   • see Anatomy of a Wiki Header

3. When linking to other Wiki pages, always use an “Inter-Document Cross Reference” with the format,

   • <<path/to/wiki/page#,custom label text>>
     The # sign substitutes for the file extension. This type of link will first look for the .adoc file and if not found default to the .html version.

     The path should be relative to the asciidoc folder.

     For example: <<jme3/requirements#,Software and hardware requirements>>
     links to the requirements.adoc page, which lives in a sub-folder of asciidoc named jme3.

     See http://asciidoctor.org/docs/user-manual/#inter-document-cross-references for more info.

4. When linking to images stored in the wiki repository, always use an image prefix in front of the file name and square brackets after it with the format,

   • Image on its own line - image::path/to/image.jpg[image alt text,width=" ",height=" ", align=" "]

     For example: image::jme3/beginner/beginner-assets-models.png[beginner-assets-models.png,320,250,align="center"]

     • This image is on its own line.

     • Is stored in the jme3/beginner folder which lives in the images folder.

     • Is named beginner-assets-models.png.

     • Has a alt text name of beginner-assets-models.png.

     • Has a width of 320.

     • Has a height of 250.

     • Is aligned in the center of the page.

   • If you want to include an image inline, use the image: prefix instead (notice there is only one colon):

     See http://asciidoctor.org/docs/user-manual/#images for in depth instructions.

Build

• In Netbeans, convert the AsciiDoc to HTML5 by invoking the 'asciidoctor' goal:

   $ ./gradlew asciidoctor

  Open the file build/asciidoc/html5/index.html in your browser to see the generated HTML file.

• In Atom, you see real time changes when using the AsciiDoc Preview (ctrl+shift+A or Packages › AsciiDoc Preview › Toggle Preview). No build is required.

TODO

• ✓ configure travis build

• ✓ configure github + gradle + travis to publish on gh-pages branches

• ✓ find and fixe conversion bug

• ✓ complete conversion: note, warning, …​

• ✓ fix warning during html’s generation (should be fixed manually)

• ✓ add meta info during conversion (doctitle, revision, tags, …​)

• ✓ add a home page (index.html)

• ❏ add a navigation bar or a menu (?)

• ❏ customize html layout (header, footer, css)

• ✓ transfer ownership to jMonkeyEngine org

• ✓ complete Doc, how to contribute,…​

• ❏ accept Pull Request

• ❏ write a post about the migration (the tools, why asciidoc, vs alternatives, how …​)

• ❏ generate sitemap

• ✓ add search box

• ❏ add google analytics (?)

• ❏ support emoji

• ❏ support iframe block

• ✓ fix slideshow of "Xxx for Dummies"

• ❏ optimize remove useless images

• ❏ optimize image, use smaller file, eg convert to jpg or to webp, resize

• ❏ organize i18n / lang

• ❏ use tags to create taxonomy