New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Wiki #463
Comments
Thanks for starting the issue and pinging me, I've been waiting a long time to actually get things going faster :P What wikis have people made already?There is a WIP 3.5/Classic Wiki on Wikia, and one for beta that TCEO, Sonnicon, Jibbyy (who Is inactive I think), and I have been and are (slowly) working on on GitLab. The latter has a roadmap thing that I am also trying to update regularly and as I make changes. Which wiki provider looks the best and is easiest to use?Many people have different opinions on this, most believe in Wikia to be the best, but I personally think that an mkDocs site that is visually simpler, albeit with a bit of a learning curve if you have not written in any markup language before. I will list each of the personal pro's and con's I see on each one, and preliminary sorry because I am a tad biased towards Markdown: WikiaPros
Cons
Markdown/MkDocs/GitLabPros
Cons
Which wiki sites support easy autogeneration of pages?Specifically how and what? It might be easy to implement it into mkDocs or just make a script that makes markdown files from information. AFAIK, mkDocs does not natively support it, nor does Wikia. Can ads/paid wikis be avoided?Yes, completely, using GitLab Pages, where the WIP beta wiki is currently being worked on. Can we get away with a wiki on GitHub?I would strongly recommend against it. GitHub wikis are primarily used for extra info and documentation, but even so, people still use markdown files, their own README, or GitHub/GitLab pages and an easy documentation system for their documentations. Limited space, and slower because there are more unecessary components. Thank you again Anuke for posting a question like this; the wikis really need to be worked on and I think this will gather the sort of attention and ignite discussion that pushes it forward, especially considering random members of the discord participate on useless discussions and s-post issues ;P
|
Alright, we'll go with the GitLab wiki for now and consider other choices if issues arise. I still think it's a bit early to start writing the wiki pages themselves (as content will still change before release), but it's worthwhile to start coding the system for creating and managing the pages. Unlike some other games (e.g. Minecraft), Mindustry already has a sort of wiki for its content in-game. It would be a waste not to use this information to automatically generate pages each release. How I envision it would work
Potential issues with this systemIdeally, I would like each content information page to consist of an autogenerated page that is updated each release, along with a user-created section which lists additional information such as strategies, additional info, trivia, etc. A simple way to do this would be to have an HTML comment in the middle separating the autogenerated section, with everything above it being automatically replaced every release. Would this be too confusing/obstructive for wiki editors? I'm not sure. |
I agree with the auto-generation system, although I, sonni and tceo would have to put much further thought into that. It's not too hard to create a simple js script that just modifies parts based on a regex or something but neither is it a trivial subject. Currently, I see that as a big help since I have to manually re-sprite stuff and edit a lot of tables and things manually. If there are specific parts that are dynamic, that would be amazing:
HTML comments that act as delimiters imo will be effective. I might be able to get a proof-of-concept up by like tomorrow using
I don't think that would be too obtrusive. You've asked at the right time when areas that are too human aren't a large part of the wiki yet.
Could you possibly get all you need from just the item definitions (e.g. files like core\src\io\anuke\mindustry\content\Items.java)?
IMO that is necessary. Seeing that this wiki is called a "documentation" there should be some sort of overlap between the two functions. This would be especially useful for people that would like to contribute to the game. P.S. have you seen Jibbyy anywhere on the discord since I left? |
Do we need a roadmap on the wiki? I think a link to the Trello should be enough.
For very simple content like items, technically yes, but I would highly recommend against it. For blocks, however, it's out of the question. Many types of blocks have dynamic stat definitions based on multiple levels of inheritance, and attempting to extract that kind of information automatically would be... unwise. Writing a page generation system in Java to integrate with the game would be the best option in this scenario.
They appear to have sent a few messages since then, yes. Why? |
I mean this one: https://docs.google.com/spreadsheets/d/1wIRdj09dGPf28hX6y-YM_uP2Xp78T11raeDPbm21Ee8
Ah, I see.
I've assigned a branch to him which he abandoned and I would like to have him back for even a short time to finish it up so I can merge it with master. |
Finished my proof of concept, all without any external modules. https://www.youtube.com/watch?v=4jBeIgtmEeA WARNING - FILTHY CODE: https://gist.github.com/Luxray5474/f8bcc7d8a4e1ddb0d36deb975a16d848 Also, as you can see, the delimiter isn't actually an HTML comment, but is an empty hyperlink. I've tested it on mkdocs, and it does not appear. Some really nice optimizations. |
That works, but what we'll need for the production version is a server that listens to specific events (e.g. release event webhooks) and:
(yes, I know the last message was 2 weeks ago, I just decided to get back to this issue since 73 was just released) |
I was waiting lol. I see the efficiency in that, and since you know java much more than I do, you can actually go ahead and start on it now. I don't think conferring with tceo and sonni would help at all. 📄 The reason why I made a js proof of concept and made it take in web requests was because originally I thought of the script to just send a large file full of the stuff to the server with the js program, which then processes it, but that is inefficient obviously. Also, as opposed to a standalone server, why don't you just use CI? Can't you just set it to trigger on a specific event? edit: also I spent wayyyy too much time trying to figure out how to batch the entries into files over the week and I only finished it today which is conveniently the same day you post that message lol. |
Good point. I suppose I could set up a system where the Mindustry CI clones the wiki repo, runs the script and pushes the files. |
Any other thoughts? Also, I agree with the idea of the program doing all the things instead of having two separated programs communicating over the internet. I think it would be more secure. |
I'll bring up any issues I find with the wiki system here. For now, I've created the generator repository |
Awesome. And now, I have a nice markdown updater i might publish later on, because of the usefullness of its concept :D One thing, because of the nature of CI, virtual 'disk space' is cleared when a pipeline ends, and cloning the repo every single time is quite inefficient, especially in the future when it will be full of images and maybe other media. Maybe that's our only choice though. |
Unless it takes actual hours to clone and run, I don't think that will be an issue. As long as the wiki gets updated within a day of release, it's fine. |
How do translations work with the Gitlab wiki? I'm considering implementing the generation system using bundles of template text, similarly to how the main game functions. Is this worth the effort? |
Not yet. My plan is to begin the translation of the wiki once it has gained a considerable amount of contributors (and readers), even more so if they come in a wide range of ethnicities. One that's begun, we'll only be focusing on 5 major languages, or the 5 most used languages in the game's userbase (which will be easy because of the appalling amount of people we have in the discord which imo represent the (unseen) userbase as a whole more than well), maybe adding more if there are, well, more. |
Awesome :D Would you like me to setup a test repo for the wiki, so you can dabble with it? Also it can update pages too right? (it's main function) (also, what IDE are you using? it looks real slick) |
The generation system is more or less done now. There's still a lot of info missing, and only 3 types of content have generators, but the core of it is complete.
I think we should move on to creating the real repository for the wiki.
Yes. It can splice new generated page content in before the old stuff. |
Wait so, we're making a new format for the all wiki pages?
Please clarify 😕 We already have a repo. |
I thought that was general documentation for modding, not the location for a new wiki. It seems a bit weird to have an official wiki at mindustrymodders.gitlab.io.
I'm not entirely sure what you mean by 'new' format. While the wiki you posted previously has files for blocks, they're all merged into one page and missing a lot of details-- it's not the same thing at all. |
Ohhh, well then, I'll move over some stuff to a new repo this weekend probably.
Obviously it is not done yet. If you look at the planner I am still working on getting items done (really slowly). Here is the hierarchy:
Each content type is a 'folder' in the sidebar. The category is one big file that starts with a table. The 'members' are subheadings of the file separated by to make them their own 'portion'. Of course, each 'portion' would be treated as if it were a page, with all of the information about the item, etc. Why that instead of separate files? 1) It leverages one of the features of the sidebar in mkdocs, each subheading looks like its own article, and therefore can be treated as such, and 2) it makes a more streamlined and concise reading and writing experience. The other thing you are looking for is just a short scroll away, and you go through less folders when editing. |
I'm not sure about this. We could have a (autogenerated) main block navigation page with links for every block separated by category, but individual blocks should stay separate. Each block may have a lot of information available about it; it would be cleaner to have a separate page to prevent clutter. This is what every other wiki I've seen does, and it seems to work well. Another side-note is that putting all the blocks into one file makes splicing significantly more difficult. |
Sure, I guess. I'll try to divide it this weekend too. |
Wait, why divide it? Are you referring to the block pages? |
Yes, since they already each have like a couple paragraphs-full of information. Also, please confirm to me the page format/layout you decide on when you do. |
These pages? I don't see what you mean. This is all information that will be automatically generated in the block pages; why keep it? I don't see any of the pages in the current |
https://gitlab.com/MindustryModders/mindustry-documentation/blob/items-rev1/docs/items.md |
From what I can tell, the only information we can use from those pages is the descriptions. Everything else is (or can be) generated. The splicer expects files to be generated first, then descriptions and such to be added later. I don't think you should split anything up until the generated content is working on the main wiki. |
Ohhhh, now I get it. I'll setup a GitLab Pages repo (why not github? ask tceo.) rn and give you a token privately afterwards so you can begin generating the files. |
I've asked TCEO, and he hasn't responded yet. But, regardless, I don't think we should put in on Gitlab pages unless it has some feature that GitHub doesn't. For one thing, I don't have a GitLab account, and for another, it's simpler to keep everything on one site. EDIT: Not that it changes my stance on the subject. |
Alright. I'll see if I can import it into GitHub. Do you think we should setup an organization so we can put all repos (arc, mindustry, wiki, wikigen) under one 'name' and 'hub'?
|
I already have something resembling an organization here. Not sure about moving the main Mindustry repository there, though. |
Then, you decide. The reason I suggested putting it under a group is it seems a little weird to have a wiki with many (potential) contributors under one name. One thing is I wouldn't like to create it under my name. |
I could invite you to the organization, and you could create the wiki there. I don't think anything besides the wiki tools and site should be under the organization, though. |
Perfect. 👍 |
@Anuken I am going to use Travis CI as a deployment tool according to this StackOverflow answer https://stackoverflow.com/questions/50892018/auto-build-an-mkdocs-documentation-in-travis-ci. It needs organizational access though. |
Which access level do you need? |
I don't see anything about a request; no notifications and nothing showing up in the organization page. What does the info button say? |
Found it in my email. Should be approved now. |
Thanks 👍 |
I see the wiki builds now. Should I begin testing the page generation system on the wiki's directory structure, or are you planning on making more changes? |
I will make a branch for that soon. |
Done. Please read the included document. https://github.com/MindustryGame/wiki/tree/wikigen-project |
Which included document? There's quite a lot of them. |
In the |
Please assign the sprite the ID BTW, I apologize for not being able to contribute in a long time. I've been catching up on school and finishing up the semester, plus studying for exams. |
Can I help you with this? 🤔 |
Well, what we could use help with is the styling of the actual wiki, plus some improvements to Anuke's bot which generates the actual pages right now. If you know how to work with HTML and Jinja templates, which mkDocs uses to actually generate the basis for pages, you are more than welcome to start a PR and work on these changes! |
Now THAT is a wiki! Bravo :D We should probably remove those buttons. People can click on the next article anyway. |
@Luxray5474 with the broken icons for mobile, can't you just use the % unit and float stuff to the side? |
Please go and check this out. Although, I don't see anything particularly wrong? (except for the hamburger menu icon being offset up slightly) https://i.imgur.com/RZuWZkR.png Also I don't really know if this looks like this on true mobile; my phone broke ages ago therefore I am using Firefox Devtools' mobile device simulation feature.
|
Small update: The Mindustry Travis script now automatically updates the wiki on each commit. Near final release, I'll switch to updating only on releases. |
Since the wiki is more or less operational now, I'll close this issue and open new ones for specific topics over at the main wiki repo if needed. |
This is a discussion issue for this card on Trello.
Pinging @Luxray5474 for input.
The text was updated successfully, but these errors were encountered: