Please welcome a new member to the Wiki team. @8Keep123. He has an extensive knowledge of everything code and will be a great asset for us. His trail blazing work with what is revealed below has been irreplaceable.
I would like to introduce to you a new way to wiki. @8keep123 and I have been working on a new site and user interface that will bring the wiki up to modern standards.
The genesis for the change is the fact that the current wiki design is hard to maintain, version and the user interface is part of the documentation repo. Not to mention, those who may take over the wiki one day, would have to figure it all out from scratch so most will not even want to try. I don’t want to waste more time on the negatives, so I will let you see what the new site looks like and describe some of the potential this design brings with it.
The site:
https://mitm001.github.io/docs.jmonkeyengine.org/docs/documentation.html
The demo repo for the docs:
https://github.com/mitm001/docs.jmonkeyengine.org
The demo repo for the User Interface:
This uses the Antora site generator for building and maintaing documentation.
What are the benifits?
- Right off, the most powerful is Modularity. We can separate documentation into modules, use simver to version those modules, and the modules do not need to even be part of the wiki. Anyone can add an Antora folder structure to their own site with what’s known as an antora.yml file and nav.adoc file and the wiki can pull in that site with just a couple lines of code added to what’s known as the playbook.
- These offsite modules can be maintained by their owners. If a particular module becomes so outdated the official wiki no longer wants it, we remove three lines of code and its gone. Nothing special needs to be done. We can maintain our own modules that relate to the jMonkeyEngine without having to maintain unrelated work. The SDK comes immediately to mind. The current wiki SDK docs could be moved to the SDK repo, a couple files later and its completely independent of the official wiki, has its own documentation and can still be a part of the wiki
-
Antora is well documented and easy to learn. Anyone taking over the wiki will have a much easier time getting a grasp on things. Contributors will have a much easier time contributing. They aren’t even required to host their content on the wiki itself. No more wiki clutter.
-
Another huge benefit is versioning. Antora was designed to work with repositories. So it uses what’s already there for its versioning. All we do in a playbook is add a branch value and that now is part of the wiki. So for example, the module has a master, v3.2.4 and 3.3.0 etc, we can pull any or all of those branches for a module into the wiki with a single value like so, [master, 3.3.0]. That’s it, we have a master and 3.3.0 version. Antora will only show the changes that were made when you visit that doc page, with the highest version taking precedence. If a page you visit has no changes, no other version selection option for that page will be available.
-
Next comes docs setup. Antora uses asciidoctor for the HTML conversion, exactly as is used now. We also lose the need to set headers in the doc files as Antora has all the header attributes we currently use built right in. Give your document a title and your set. You can add an author to your page or not. Up to you. You dont have to set attributes to use macros like now, you just use them. Want an emoji, just add it emoji:smiling_imp[2x]. No header setup needed.
-
Note that we have an overall navigation menu on the left of the UI and table of contents for any page selected on the right. The nav menu is just for demonstration right now since the wiki is not modularized yet. Once that happens, each module will have its own nav menu and we would have a better flow to it. We can add or remove modules that the team may or may not want. Another great aspect of the Antora generator is pagination. If you look at the bottom of any page selected from the menu you will see that Antora can provide links to the next and previous menu item. No more manual setting of these as links in a page and having them break if you move things around.
-
Next comes UI separation. The UI is completely independent of the docs. It has its own repo and changes that are made there control the user interface for all modules. The templates use HTML, JavaScript and CSS language that any web developer is accustomed to already using. Big win.
Did you notice you can change the theme? Click that toggle button in the top navbar. Pick your poison. -
Next, the whole build process uses GitHub workflows. The docs always pull from the UI site the latest release anytime they are built. The UI pushes new release just like is done with the engine using tags. A pushed tag will notify the docs site workflow a new UI has been released and the doc site will run its workflow, updating its UI. The whole build process for the wiki docs now would be simver based releases that can be tied to the engine release schedules.
To demonstrate the power of the playbook. If you open the window in the bottom left of the docs, you will see that there is a module that says jMonkeyEngine UI. That module is located on the jme-ui website.
If you look at the playbook, you will see it’s all of three lines to drag that module into the wiki.
If we had a version branch, it would be a simple thing to add the branch to the branches key and that version gets brought in with it, only the changes though. Just like how GitHub does things.
We await your questions and hope you all decide this should be the future for the wiki.
so we weren’t able to try that yet
(at least if someone know Antora)