Publish API Documentation for Master Branch

bevyengine / bevy

A refreshingly simple data-driven game engine built in Rust

https://bevyengine.org

Apache License 2.0

36.36k stars 3.59k forks source link

Publish API Documentation for Master Branch #407

Closed zicklag closed 2 years ago

zicklag commented 4 years ago

I was just thinking that it would be useful to have the API documentation for the master branch published to GitHub pages somewhere.

I was going to explain to @lee-orr, a beginner Rustacean, what changes were going to need to happen for #397, but I noticed that some of the API that I was going to point to had not been released yet, which meant that I can't point to the documentation for it. I didn't end up needing it in that case, but it seems like it could be useful.

CleanCut commented 4 years ago

I suggest avoiding adding to the overhead of the project at this early stage. There's a lot of things like this that are nice, but quickly add up to a lot of infrastructure complexity and maintenance. Rather than serving up API docs for master, I think it would be more healthy to:

Release very frequently, so there isn't much desire for referencing the master docs
Show folks how to generate their own master docs locally (It could just be a sentence at the top of the API docs front page, for example)

zicklag commented 4 years ago

I'll buy that. :slightly_smiling_face: :+1:

memoryruins commented 4 years ago

That would be useful (now or eventually). I imagine something like cargo doc --no-deps -p bevy so that it doesn't include docs for all dependencies too (which is what I use locally). It would also help the users of git versions to help audit the docs in-between releases.

Moxinilian commented 4 years ago

If the master docs are ever provided on the website, it is of utmost importance search engines do not reference it. Amethyst had a ton of issues with people being misdirected into the wrong documentation.