Plan for documentation and site

[badosu]

So as you may or not know I've been working for some time on documenting the Spring <-> Lua API (I'll use Spring name for API and internal references for the time being and avoiding confusion). The draft PR is present at #542

As LDoc creates a documentation page in html (no decent markdown output unfortunately, though easily hackable to do it), it makes sense that we should update and publish the documentation on each commit to BAR105. With this in mind I also created a github action workflow to perform this duty. It commits only the subtree present on doc/site to a branch called gh-pages.

When github receives a commit to gh-pages it automatically deploys a github page accessible via <org>.github.io/<reponame>. For now we only run ldoc and spit it's html to doc/site/doc, redirecting from / to /doc. You can see it in action here.

With all this in mind it also automatically creates infrastructure for maintaining a Recoil website managed internally on the repo (or can be done with a submodule cloning to doc/site if necessary). You can put any html on doc/site and it will work as if served by an http server like nginx.

Furthermore github internally uses jekyll for gh-pages, which we are not necessarily required to use, but would enable us to simply drag and drop a theme like this and manage content with simple markdown. Again making it extremely easy for developers to maintain engineering, news, and documentation content. Alternatively, and I know some BAR folks have proficiency with tools like the ones used on beyondallreason.info that can be used.

I think this is a good timing with the rebranding and all, so just wanted to put some thoughts out there and ask for feedback.

In a way or another I'll keep working on LDoc as I think it is indispensable for the future maintainability of the API. And allows for cool stuff like this as a bonus (with possibility of hacking LDoc to also spit sumneko and ZBrane compatible output from the AST):

[badosu]

See also #542

[lhog]

I'm all in for github hosted documentation site i.e. <org>.github.io/<reponame> and simple approach with standard themes/templates.
I also noticed you switched from standalone documentation file to in-source markdown to generate the documentation - very good move!

Besides the docs it'd be nice to reference the games using the engine (w.e it's called moving on), but that and other small things would be a cherry on the pie, and the pie is the updated and accessible documentation. Keep on going, you're doing great!

[badosu]

Site is available at https://beyond-all-reason.github.io/spring/, autogen docs at https://beyond-all-reason.github.io/spring/ldoc.

The infrastructure is available to be used. I'm closing this discussion.