Yes, I don’t like the black theme either. It’s too hard for eyes. I think the light white theme is better.
Where’s the new Wiki layout?
Is it this one?
https://mitm001.github.io/docs.jmonkeyengine.org/docs/documentation.html
Looks very nice!
Maybe you guys can even help the SDK out. Originally it did download the wiki using some xhtml_export link addition on a premade number of links.
I guess asciidoctor makes it a breeze to convert those files to be SDK ready (I think the most critical part is linking to the online version)
Edit: See Wiki Support as in-sdk help · Issue #192 · jMonkeyEngine/sdk · GitHub for an analysis I did on the old wiki
4 Likes
The only problem I see is that search will never work offline. It works through Algoria, who run the indexing and host it themselves.
The search tool (algolia) hasn’t changed from the current wiki though. There are alternatives that are purely client side but would require a lot more custom work (and maintenance). Lunrjs is one
And @Darkchaos, it would probably be helpful to include an offline version of the wiki, even if it doesn’t include search, because we now have a side navbar that gives much more visibility to wiki pages than before, helping you get to where you need to go.
My idea is to setup an antora module on the SDK site. You can do with that whatever you want. All we would do in wiki is pull it in as a content source. That would give you full control of where things go.
Edit: By setup, I would move all existing SDK documentation in the wiki to the SDK. It can be in any folder you want as long as it follows the antora requirements.
https://docs.antora.org/antora/2.3/standard-directories/
Edit 2: Why not just keep SDK only content in SDK repo and have people use the official wiki for everything else? Thats what I am getting at.
@mitm,
@Darkchaos is just talking about the offline wiki included in the sdk, which would be the entire wiki, not just the sdk module
To clarify what mitm is talking about: Antora lets us have “modules” that can be included or not included very easily. These can be hosted in any git repository, not just the wiki repo.
1 Like
I wonder if netbeans doesn’t support indexing and a search on their behalf, but even if not it’s probably better than nothing. Though I guess in the current times everyone has internet access, but it might just be more convenient to have it integrated.
The 3.0 Wiki probably does more harm than good atm though
I’ll add it to my todo list, there’s still plenty to do after migration still. The versioning support really opens us up to more progress in updated many outdated wiki pages, because people can easily switch to an older version. I think the current wiki will be locked to a 3.2 version, and work can start on the 3.3 wiki, and if any big new features get added to master, a master version can be started as well. These are essentially just git branches so we can branch off at any time and still merge specific changes to older branches.
I need some time to think about the best way of generating an offline version.
I’ve added you to the wiki team @8Keep123 - and thank you for all of your efforts both of you.
3 Likes
I have given this a quick look and think this may be doable using a github workflow. I notice that you are using the java action actions/setup-java@v1 to setup java, not sure if it makes a difference but there is this action GitHub - joschi/setup-jdk: (DEPRECATED) Set up your GitHub Actions workflow with a specific version of AdoptOpenJDK to use adoptOpenJdk.
First thing is, the wiki setup will have what you want in modules, every module always has the same family structure with images, pages, resources, etc. so you wont have to worry about breaking changes unless a module gets renamed or moved.
All the files already have header attributes, only new content wouldn’t have any so for awhile you would be ok. Even without the attributes, should be ok. You could even output the files without header and footer, body only for your own template.
You could clone the wiki (where only docs live) from the work flow.
Convert whatever module/.adoc files you want into html using,
you wouldn’t need to learn asciidoctor then, Just a few commands and convert whole directories.
Set the style sheet,
https://asciidoctor.org/docs/convert-documents/#styling-the-html-with-css
Move the converted files where you want in the environment and commit them, including images, your own css, whatever is needed.
Setup the workflow to only work on pushed tags or just add a gradle task you run when ready to build the docs.
This way, you don’t try to feed off the wiki gh-pages branch because those html files are designed for use with the wiki-ui and have ui specific values.
Edit: We wont leave the SDK out in the cold. I or we will help get it right, if possible.
1 Like
So the “family directories” should all reside in the same repo as Minie’s source code, with “antora.yml” and the “modules” directory in the top-level directory of the repo … correct?
Any repository but yes it can be with source. If you update the docs and you issue a release branch we can pull in different branches and version them based off branch name or custom name.
It can be yes.
Wherever modules is then the antora.yml is.
Wherever the pages folder is, the nav.adoc file is.
The minimum setup.
-modules/module-name/pages/file.adoc
-antora.yml
You should read the differences between that and using ROOT.
https://docs.antora.org/antora/2.3/root-module-directory/
Edit: usually github uses docs as top folder.
1 Like
Thanks for the tips.
Minie seldom creates branches for releases, only Git tags. Can you version its documentation based on a Git tag?
Edit: And the module name for Minie documentation could be “Minie”, correct?
yes but, theres consenquences for you.
https://docs.antora.org/antora/2.3/content-source-versioning-methods/#version-content-using-tags
1 Like
Yes.
Edit: minie, lowercase
1 Like
https://docs.antora.org/antora/2.3/module-directory-names/#selecting-module-folder-names
In the antora.yml name should be lowercase, title whatever you want.
name: jmonkeyengine-ui
title: jMonkeyEngine UI
version: master
nav:
- modules/ROOT/nav.adoc
Name shows in the url in the UI,
https://mitm001.github.io/docs.jmonkeyengine.org/jmonkeyengine-ui/index.html
Title shows in the modules window when toggled,
1 Like
After reading further, I plan to name the initial module “minie-library”. That way if I later decide to document Minie’s design, roadmap, build procedures, and/or example apps in Antora, those modules won’t get confused with the library module.
I don’t have my own website. Does JMonkeyEngine have a playbook I can use?
You don’t have to have a site unless you want one, i.e using a playbook. Just the module and antora.yml in the repository. Thats all it takes for us to pull it in.
You can use github pages for free with a workflow to build using node.js, just like wiki, if you want a full featured site.
1 Like