search

MovingBlocks / Terasology

Terasology - open source voxel world
http://terasology.org
Apache License 2.0
3.67k stars 1.33k forks source link

Auto-doc block shapes for wiki with sample(s) included #508

Open Cervator opened 11 years ago

Cervator commented 11 years ago

We're getting more and more block shapes and they aren't very obvious (outside of getting the list via console in-game). I suspect it would be doable to auto-generate a GitHub wiki page listing all the shapes and if a sample image following a naming convention is included with the shape definition then include that on said wiki page as well.

Can pretty much do the same with other blocks. Lots of possibilities to script markdown + git + publish to GitHub Wiki :-)

Cervator commented 7 years ago

Removing from the old v1 milestone and linking to https://github.com/Terasology/Sample/issues/1 which would be a similar cool extension to the auto block system that works now.

May also relate a bit to #1487 and #1402

kaubster commented 4 years ago

Hi, I recently discovered Terasology. Very cool. Given this is an older issue, I assume no one has expressed interest? I think it might work well as an entry issue to familiarize myself with the project.

I did join Discord if that is a better way to discuss the issue.

Cervator commented 4 years ago

Hi @kaubster and welcome! Yes surprisingly despite being filed almost 7 years ago this is still valid since it is somewhat of a nice-to-have.

For some bit more up-to-date example code you could look at #3253 - while not quite the same that tool scans the codebase for things marked @API then summarizes it all. A similar desire exists for specifically scanning for Event classes and such to then improve the documentation. It would be nice to have the events listed separately.

Exactly what to do here I'm not exactly sure about today, any more than I was 7 years ago (oh boy, hi me-from-7-years-ago). Since then we've moved a lot of shape assets out into module land, for instance see https://github.com/Terasology/StructuralResources

There's also a module browsing site now that lists some basic details about modules, maybe a shape preview would fit there and be something we could parse during code builds.

Being able to show an image of a shape would be nice, but we don't necessarily want to add such screenshots to any given repo. We have a new'ish utility that can run the game automatically, take some actions autonomously, then in theory take screenshots, but that might be a tad elaborate. Maybe there's something standalone and simple that can just preview

Finally there's also a desire to show a 3D preview in-game like in a menu screen. That's a whole other thing too though. Lots of possibilities in this area, still.

Clear as mud I'm sure, but if you poke around and get any good ideas how this might get documented / previewed somewhere do chime in on Discord, easier to discuss in detail there :-)

kaubster commented 4 years ago

Great!. I will start poking and review the examples you provided.

After posting last night I started to look for insight on formatting GitHub wiki's. I found Wicked. It scans jsDoc but might provide a shortcut to gen a wiki page quicker. I'd use Java though to scan or reflect for @Api, JavaDoc, the .block files, etc via CI. The entry-point could take arguments or read a config file to configure what to scan.

We could go further and possible do a change log between commit versions or something. Who knows.

Will ping once I have something more tangible.

Cervator commented 4 years ago

That looks neat! We've somewhat waffled over time on whether to use GitHub wikis or static sites or even both. So any sort of tooling that could help make that an easier pick would be cool. One of my earlier workflow diagrams used the GitHub wikis as a sort of staging location via mix of automation and hand editing if needed, then we'd write off a static set of docs for releases and make those available for reference somewhere else. Now it might make more sense as a CI step since we already use that to generate the module site, but I dunno 🤔

kaubster commented 4 years ago

Quick update... PR #3966 created

So far I've written a scrapper that loads a headless game and exports details, extensions, dependencies, events and derived events for game and remote modules.

I created a sample Module Wiki Gist here.

I wanted to touch base before moving on to ensure I'm on the right track.

Game and remote module details so far: