a wiki for jMonkeyEngine
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 1293 commits ahead of Nehon:master.
Latest commit 18bda6e Oct 21, 2018

README.adoc

Build Status

jMonkeyEngine 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 :

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

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.

  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.

  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