java
/
jMonkeyEngine-wiki
mirror of https://github.com/jMonkeyEngine/wiki.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542
							<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>Wiki Admin :: jMonkeyEngine Docs</title>
    <link rel="canonical" href="https://wiki.jmonkeyengine.org/docs-wiki/3.8/wiki_admin.html">
    <link rel="prev" href="wiki_contributor.html">
    <link rel="next" href="emoji.html">
    <meta name="generator" content="Antora 3.0.1">
    <link rel="stylesheet" href="../../_/css/site.css">
<meta property="og:image" content="https://wiki.jmonkeyengine.org/_/img/iconx128.png">
<meta property="og:description" content="Wiki Admin">
<meta property="og:title" content="jMonkeyEngine Docs">
<link rel="stylesheet" href="../../_/css/site-extra.css">
<link rel="stylesheet" href="../../_/css/vendor/docsearch.min.css">
<!-- fetched from https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css -->
<link rel="icon" href="../../_/img/favicon.ico" type="image/x-icon">
  </head>
  <body class="article">
<header class="header">
  <nav class="navbar">
    <div class="navbar-brand">
      <a class="navbar-item" href="https://wiki.jmonkeyengine.org">
        <img alt="" src="../../_/img/jme-logo.png" height="32" type="image/x-icon">
      </a>
      <div class="navbar-item hide-for-print">
        <input id="search-input" type="text" placeholder="Search docs">
      </div>
      <button class="navbar-burger" data-target="topbar-nav">
        <span></span>
        <span></span>
        <span></span>
      </button>
    </div>
    <div id="topbar-nav" class="navbar-menu">
      <div class="navbar-end">
        <div class="navbar-item theme-switch-wrapper">
          <label class="theme-switch" for="checkbox">
            <input type="checkbox" id="checkbox" />
            <div class="slider round"></div>
          </label>
        </div>
        <a class="navbar-item" href="https://github.com/jmonkeyengine/wiki">Github</a>
      </div>
    </div>
  </nav>
</header>
<div class="body">
<div class="nav-container" data-component="docs-wiki" data-version="3.8">
  <aside class="nav">
    <div class="panels">
<div class="nav-panel-menu is-active" data-panel="menu">
  <nav class="nav-menu">
    <h3 class="title"><a href="wiki_contributor.html">Wiki Contribution</a></h3>
<ul class="nav-list">
  <li class="nav-item" data-depth="0">
<ul class="nav-list">
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="wiki_contributor.html">Contributor</a>
  </li>
  <li class="nav-item is-current-page" data-depth="1">
    <a class="nav-link" href="wiki_admin.html">Admin</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="emoji.html">Emoji</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="atom_editor.html">Atom Editor</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="atom_snippets.html">Atom Snippets</a>
  </li>
</ul>
  </li>
</ul>
  </nav>
</div>
<div class="nav-panel-explore" data-panel="explore">
  <div class="context">
    <span class="title">Wiki Contribution</span>
    <span class="version">3.8</span>
  </div>
  <ul class="components">
    <li class="component">
      <span class="title">JME</span>
      <ul class="versions">
        <li class="version">
          <a href="../../docs/3.8/documentation.html">3.8</a>
        </li>
        <li class="version">
          <a href="../../docs/3.4/documentation.html">3.4</a>
        </li>
        <li class="version">
          <a href="../../docs/3.3/documentation.html">3.3</a>
        </li>
        <li class="version">
          <a href="../../docs/3.2/documentation.html">3.2</a>
        </li>
      </ul>
    </li>
    <li class="component is-current">
      <span class="title">Wiki Contribution</span>
      <ul class="versions">
        <li class="version is-current">
          <a href="wiki_contributor.html">3.8</a>
        </li>
      </ul>
    </li>
    <li class="component">
      <span class="title">Wiki UI</span>
      <ul class="versions">
        <li class="version">
          <a href="../../wiki-ui/index.html">master</a>
        </li>
      </ul>
    </li>
  </ul>
</div>
    </div>
  </aside>
</div>
<main class="article">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<nav class="breadcrumbs" aria-label="breadcrumbs">
  <ul>
    <li><a href="wiki_contributor.html">Wiki Contribution</a></li>
    <li><a href="wiki_admin.html">Admin</a></li>
  </ul>
</nav>
  <div class="edit-this-page"><a href="https://github.com/jMonkeyEngine/wiki/edit/master/docs-wiki/modules/ROOT/pages/wiki_admin.adoc">Edit this Page</a></div>
  </div>
  <div class="content">
<article class="doc">
<h1 class="page">Wiki Admin</h1>
<div class="sect1">
<h2 id="overview"><a class="anchor" href="#overview"></a>Overview</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The wiki consists of two repositories.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/jMonkeyEngine/wiki">wiki</a></p>
</li>
<li>
<p><a href="https://github.com/jMonkeyEngine/wiki-ui">wiki-ui</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The wiki repository holds all documentation while the wiki-ui repository is the user interface for the documentation.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="wiki"><a class="anchor" href="#wiki"></a>Wiki</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The wiki repository has a workflow that will be triggered when any push is made to the repository or whenever the user interface issues a new release. Every build, all pages are deleted and re-created. The workflow will cache the user interface under the <code><span class="menuseq"><b class="menu">cache</b>&#160;<i class="fa fa-angle-right caret"></i> <b class="menuitem">antora</b></span></code> directory if there are any changes and the cache folder has been added to the commit command.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">  # Detects any updates to package-lock.json and package.json and commits the
  # files to root.
  # see:
  # https://github.com/marketplace/actions/add-commit?version=v4.1.0
  # for use options.
  - name: Commit Packages
    uses: EndBug/add-and-commit@v4
    with:
      author_name: mitm001
      author_email: [email protected]
      message: "Commit files for CI workflow"
      # Commits these files to root if and only if there are changes.
      add: "package-lock.json package.json ./.cache/antora/*"
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This cache allows the build process to run offline.</p>
</div>
<div class="paragraph">
<p>The workflow can be configured to update the <code>package-lock</code> and <code>package.json</code> files by editing the <code>Install Node</code> command, just as if you were running this from a local repo.</p>
</div>
<div class="paragraph">
<p>DO NOT UPDATE OR PUSH THESE FILES UNLESS YOU DISCUSS IT WITH THE OTHER ADMINISTRATORS FIRST!</p>
</div>
<div class="paragraph">
<p>The workflow file <code>main.yml</code>, located under <span class="menuseq"><b class="menu">github</b>&#160;<i class="fa fa-angle-right caret"></i> <b class="menuitem">workflows</b></span>, can only be edited and pushed using either the github online interface or by using git bash locally and pushing the commit. Using the Atom Editor or git desktop git commands will fail currently at the time of this writing.</p>
</div>
<div class="paragraph">
<p>The <code>supplemental-ui</code> folder holds the content for Anotra search, the header and footer for the ui. Edit these as needed in the wiki repository, but <strong>do not edit</strong> these same files on the <code>wiki-ui</code> repository.</p>
</div>
<div class="paragraph">
<p>Technically, the entire ui can be configured from the wiki repo.</p>
</div>
<div class="paragraph">
<p>The wiki is an <a href="https://docs.antora.org/antora/2.3/">Antora</a>   site using the <a href="https://asciidoctor.org/docs/user-manual/">asciidoctor</a> syntax. A quick primer for syntax can be found <a href="https://docs.antora.org/antora/2.3/asciidoc/asciidoc/">here</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="source-files"><a class="anchor" href="#source-files"></a>Source files</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The source structure is now modularized.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ROOT - holds content that introduces new users to the jMonkyEngine, installing and features.</p>
</li>
<li>
<p>core - this is the main module for any content that is <strong>specific</strong> to an existing jMonkeyEngine class. It maintains similar directories as are found in the jMonkeyEngine <a href="https://github.com/jMonkeyEngine/jmonkeyengine">repository</a>.</p>
</li>
<li>
<p>networking - holds content <strong>specific</strong> to jMonkeyEngine networking.</p>
</li>
<li>
<p>physics - holds content <strong>specific</strong> to jMonkeyEngine physics.</p>
</li>
<li>
<p>tutorials - holds any content that is <strong>not specific</strong> to any jMonkeyEngine class, may be a generalized concept, may give direction on how to use the engine, or an article of some type about an engine feature.</p>
</li>
<li>
<p>sdk - sdk content only. This module may be moved to the sdk repository in the future.</p>
</li>
<li>
<p>contributions - existing user project pages. This is a deprecated module and will be removed in the near furture. Do not add new content to this module.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can decide if a page belongs in the core module by asking yourself a simple question.</p>
</div>
<div class="paragraph">
<p><em>Does the page explain an existing jMonkeyEngine class (excluding physics and networking) found in the jMonkeyEngine repository, without using an external application?</em></p>
</div>
<div class="paragraph">
<p>If yes, then it belongs, otherwise it needs to go someplace else.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="broken-link-checking"><a class="anchor" href="#broken-link-checking"></a>Broken link checking</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There is a workflow that can be used to check for broken links.</p>
</div>
<div class="paragraph">
<p><a href="https://github.com/mitm001/link-checker/blob/master/.github/workflows/main.yml">link-checker</a></p>
</div>
<div class="paragraph">
<p>To use it, simply create a repository, paste a copy of the workflow into the <code><span class="menuseq"><b class="menu">github</b>&#160;<i class="fa fa-angle-right caret"></i> <b class="menuitem">workflows</b></span></code> directory. Before commiting for the first time, set the <a href="https://github.com/mitm001/link-checker/blob/abddf3d5012b90186ae485073a8c1aaf15a3c447/.github/workflows/main.yml#L25">repo url</a> to point to the wiki.</p>
</div>
<div class="paragraph">
<p>If there are any errors, a <code>linkchecker.md</code> or <code>unresolved.md</code> file will be committed to your repository under the <code>checked-links</code> directory. You may need to issue a pull request after a push because of this. The typical workflow consists of fixing reported broken links, deleting all <code>.md</code> files and pushing to the repo. Then issue a pull request to see if there are any remaining problems. These files will only be built if there are errors.</p>
</div>
<div class="paragraph">
<p>If there are no files in the <code>link-checker</code> directory and you need to run a check, just create any new file in the <code>link-checker</code> directory and push it.</p>
</div>
<div class="paragraph">
<p>The reason for two files is that the <code>peter-evans/link-checker@v1</code> action is not capable of reading relative links properly. This is the only action that is available currently. However, we are in luck in that the Anotora build will set a class on any relative link that fails named <code>class="page unresolved"</code>. We can then use a grep command to parse the gh-pages branch and find any file with this class and write it to file.</p>
</div>
<div class="paragraph">
<p>This is an example of the output for a broken relative link.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">tutorials/beginner/hello_collision.html:1289:&lt;p&gt;For a detailed description of the separate jar files see
&lt;a href="#getting-started/jme3_source_structure.adoc#structure-of-jmonkeyengine3-jars"
class="page unresolved"&gt;this list&lt;/a&gt;.&lt;/p&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This gives you the file name:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">tutorials/beginner/hello_collision.html</code></pre>
</div>
</div>
<div class="paragraph">
<p>and the name of the broken link to search for in the file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">#getting-started/jme3_source_structure.adoc#structure-of-jmonkeyengine3-jars</code></pre>
</div>
</div>
<div class="paragraph">
<p>All broken links start with a <kbd>#</kbd> sign. In this instance, we have an inter document link thats broken as there are two pound signs.</p>
</div>
<div class="paragraph">
<p>The <code>peterevans</code> action will locate all broken image and web urls. There is a problem though that prevents its full use, which is running this on a schedule and automatically opening issues. When Antora builds a site, it will build links from the &#8220;nav-menu&#8221; and &#8220;Table of Contents&#8221; into every page. This will lead to <code>Too Many Requests (HTTP error 429)</code> errors. The easiest way to get around this would be to filter the href attribute class for the <code>nav-link</code> class, since we know these links are good, and skip them. This is currently not possible using the <code>petereveans</code> action. To work around it, just search the <code>linkchecker.md</code> for <code>file or directory</code> errors.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="user-interface"><a class="anchor" href="#user-interface"></a>User Interface</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>wiki-ui</code> repository has two workflows. A workflow that will build on any push (main.yml), and one that builds on pushing a tag (release.yml). If you push any tag to the master branch, a release will be created, triggering the wiki build, thereby updating the wiki cache and user interface for the wiki.</p>
</div>
<div class="paragraph">
<p>This will allow you to make changes to the ui without triggering a build unless you are ready.</p>
</div>
<div class="paragraph">
<p>The user interface uses standard html in its templates so editing should be familiar to anyone who knows html.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="versioning"><a class="anchor" href="#versioning"></a>Versioning</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There are two files that control versioning for the wiki, each serves a different purpose.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><code>wiki-playbook.yml</code> - determines what branches to use for content.</p>
</li>
<li>
<p><code>antora.yml</code> - controls module versioning.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The wiki uses branches for versioning. The current branch being used for the jMonkeyEngine is <strong>always</strong> the master branch of the wiki.  In the playbook this is known as the <code><strong>HEAD</strong></code> branch.</p>
</div>
<div class="paragraph">
<p>The <code>docs</code> module is the main module for the wiki. Its <code>antora.yml</code> file controls the version of the wiki. The playbook uses this version to create the folders inside the <code>gh-pages</code> branch, building the content from the branches configured in the playbook.</p>
</div>
<div class="paragraph">
<p>Branch version names should only target major/minor releases, not the patch of a version, and start with &#8220;v&#8221;.</p>
</div>
<div class="paragraph">
<p>When it&#8217;s time to cut a new version for the wiki, the process is as follows.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create and checkout a new branch that matches the <strong>current version</strong> of the wiki. If the current version (HEAD) is targeting version 3.3 in the <code>antora.yml</code> for example, you would name the new branch <code>v3.3</code>. Thereby preserving the current master branch content.</p>
</li>
<li>
<p>We do not want the Antora <code>.cache</code> to be versioned so you need to delete it from the new version branch if it has been commited to the repo.</p>
</li>
<li>
<p>Push the branch to the repository.</p>
</li>
<li>
<p>Switch to the <code>master</code> branch and edit these files:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Add the newly created branch to the <code>branches:</code> array in <code>wiki-playbook.yml</code>.</p>
<div class="listingblock">
<div class="title">wiki-playbook.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">content:
  sources:
  - url: https://github.com/jMonkeyEngine/wiki.git
    branches: [HEAD, v3.4, v3.3, v3.2]</code></pre>
</div>
</div>
</li>
<li>
<p>Increment the version of the <code>antora.yml</code> file.</p>
<div class="openblock">
<div class="content">
<div class="listingblock">
<div class="title">The docs antora.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">name: docs
title: JME
version: '3.4'</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">The docs-wiki antora.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">name: docs-wiki
title: Wiki Contribution
version: '3.4'</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The version value is enclosed in a set of single quote marks (') because it starts with a number. As was mentioned earlier, the module versioning is controlled by the <code>antora.yml</code> file, not the playbook, so they do not have to match.
</td>
</tr>
</table>
</div>
</div>
</div>
</li>
</ol>
</div>
</li>
<li>
<p>Edit any links found in the <code>README.adoc</code>, located in the root of the repository, that are versioned, so they match the version value you just set in the <code>antora.yml</code> file.</p>
</li>
<li>
<p>Stage, commit and push your changes to the repository.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The wiki versioning is now complete but you will need to update the docsearch repo to reflect the changes so that search works properly.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Navigate to the Algolia <code>docsearch-config</code> repo and update the search script.</p>
<div class="paragraph">
<p><a href="https://github.com/algolia/docsearch-configs" class="bare">https://github.com/algolia/docsearch-configs</a></p>
</div>
</li>
<li>
<p>From the main page, click the <b class="button">Go to file</b> button and Enter <code>jmonkeyengine</code> into the search line.</p>
</li>
<li>
<p>Edit the version line to point to the new version used in the <code>Antora.yml</code> file. In this example, the current search is targeting 3.3.</p>
<div class="openblock">
<div class="content">
<div class="listingblock">
<div class="title">Old jmonkeyengine.json</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-.json hljs" data-lang=".json">{
  "index_name": "jmonkeyengine",
  "start_urls": [
    {
      "url": "https://wiki.jmonkeyengine.org/docs/(?P&lt;version&gt;.*?)/",
      "variables": {
        "version": [
          "3.3"
        ]
      }
    }
  ],

  ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The master branch <code>Antora.yml</code> file is using 3.4.</p>
</div>
<div class="listingblock">
<div class="title">Antora.yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml"> name: docs
 title: JME
 version: '3.4'

...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Edit the <code>jmonkeyengine.json</code> file and push your commit to update the search. It takes approximately 24hrs after the commit is merged for it to take effect.</p>
</div>
<div class="listingblock">
<div class="title">Updated jmonkeyengine.json</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-.json hljs" data-lang=".json">{
  "index_name": "jmonkeyengine",
  "start_urls": [
    {
      "url": "https://wiki.jmonkeyengine.org/docs/(?P&lt;version&gt;.*?)/",
      "variables": {
        "version": [
          "3.4"
        ]
      }
    }
  ],

  ...
}</code></pre>
</div>
</div>
</div>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>Things to know about versions and component modules.</p>
</div>
<div class="paragraph">
<p>If a version isn&#8217;t specified in the target page ID (xref:[email protected][link text]), and the target and current pages belong to a different docs components, Antora will use the latest version of the target component to complete the page ID.</p>
</div>
<div class="paragraph">
<p>At the time of this writing, we have two links in the <code>docs</code> module (documentation.adoc page) that link to the <code>docs-wiki</code> module and one that points from the <code>docs-wiki</code> module to the <code>docs</code> module license.</p>
</div>
<div class="paragraph">
<p>Since this is a wiki module, we would want to point to the most current content so not versioning them is the best approach.</p>
</div>
</div>
</div>
<nav class="pagination">
  <span class="prev"><a href="wiki_contributor.html">Contributor</a></span>
  <span class="next"><a href="emoji.html">Emoji</a></span>
</nav>
</article>
<aside class="toc sidebar" data-title="Contents" data-levels="2">
  <div class="toc-menu"></div>
</aside>
  </div>
</main>
</div>
<footer class="footer">
  <p>Copyright 2020 jMonkeyEngine Wiki Contributors. Licensed BSD-3.</p>
</footer>
<script src="../../_/js/vendor/docsearch.min.js"></script>
<!-- fetched from https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js -->
<script>
var search = docsearch({
  apiKey: 'a736b6d93de805e26ec2f49b55013fbd',
  indexName: 'jmonkeyengine',
  inputSelector: '#search-input',
  autocompleteOptions: { hint: false, keyboardShortcuts: ['s'] },
  algoliaOptions: { hitsPerPage: 10 }
}).autocomplete
search.on('autocomplete:closed', function () { search.autocomplete.setVal() })
function focusSearchInput () { document.querySelector('#search-input').focus() }
if (document.querySelector('.home-link.is-current')) window.addEventListener('load', focusSearchInput)
</script>
<script src="../../_/js/site.js"></script>
<script async src="../../_/js/vendor/highlight.js"></script>
  </body>
</html>