Documentation and benchmark sites

[jaytaph]

We currently have a (not completely working) system that will deploy the current docs generated from the engine to github pages.
We also have some benchmarks, and we might get other (generated) documentation as well.

I would suggest we setup a dev.gosub.io "site", were we can deploy these things automatically.

For instance, the docs as docs.dev.gosub.io, and the benchmarks as benchmark.dev.gosub.io.

Any thoughts?

[auronandace]

I have observed in the Rust community that there are usually 2 popular approaches to documentation.

1 - As part of your code to be generated by cargo.
2 - A separate mdbook.

An example of 1 can be found here: https://doc.rust-lang.org/stable/std/
An example of 2 can be found here: https://rust-lang.github.io/mdBook/

Some Rust projects use both forms of documentation for different purposes. Often times the mdbook approach is used as a guide of how to do something or providing an overview for the project as a whole. Here is the book for Redox as an example: https://doc.redox-os.org/book/ch00-00-introduction.html

Documentation comments are either prefixed with //! or /// instead of the usual // or /* comments. One thing I thought was quite handy that the SerenityOS devs are doing in their C++ codebase for their impressive ladybird browser is including comments with links to the relevent spec pages.

[jaytaph]

It would make a lot of sense to have the current system documented from the start. But I also realize this is not everybody's favourite job to do. If we have an automated system that can generate these docs, it might be easier for people to document things.

Right now, the main website of gosub.io is automatically deployed with a simple rsync over ssh to the webserver. I think we can add some deploy steps in the github actions to generate docs, benchmarks and whatnot and automatically deploy them as well.