Updating some docs

[bailey-coding]

I was originally just trying to build auraescript, which set me on this tangent of updating docs, which now lead me to trying to get the docs working on my Macbook.

These commits and this PR description will hopefully be better once it's all figured out. Comments welcome though!

We have 99% of what's necessary to make sure the committed docs are up-to-date with the generated bits, because we have the lint and build jobs.

The lint checks for typos, so can also check if it's generating any changes or not, by doing a git diff and checking the exit code or something.

The build job generates the docs, then force-pushes to gh-pages, so the actual docs published will be up-to-date, but not the generated docs stored in the repo.

[cla-bot[bot]]

In order to contribute to a Nivenly Foundation project you must sign and agree to the CLA. Reply with @cla-bot check to check again.

[dmah42]

the workflow i would love to see is where no-one has to think about generating the docs. this means one of two things:

1. make generates the docs automatically, just as it generates the .rs and .ts files today
2. a github action generates and commits the docs on merge to main

i don't have an opinion either way on which option we go with, but we should pick one and make that the One True Way.

[bailey-coding]

That sounds good.

I think the first option sounds simpler, though at the same time I'm not 100% sure what needs to be done for that.

[bailey-coding]

@cla-bot check

[cla-bot[bot]]

The cla-bot has been summoned, and re-checked this pull request!

[dmah42]

That sounds good.

I think the first option sounds simpler, though at the same time I'm not 100% sure what needs to be done for that.

i think it is simpler. it would be a matter of having some mapping from input proto/rust file to output doc and then a target in make. then that target should be a prerequisite for testing or installing or something.

an even simpler version would be to have a target in the Makefile that creates the docs from the proto/rust that is a prerequisite for test targets or something.

[bailey-coding]

Another discovery! The auraed crate's docs are missing from gh-pages, because of specifying --target, so they end up in target/${MUSL_TARGET}/doc instead of target/doc. 🙃

[bailey-coding]

I might have veered a little off the track, but I'll look at this some more during the week and figure it out.

[bailey-coding]

I think I should maybe break this PR into multiple, because the diff doesn't make it super obvious now what is:

• moving docs around - to be able to more easily generate them and avoid duplication and keep them in sync
• drift between committed and generated docs - which shouldn't be a problem if we don't commit any generated docs
• making sure our generated docs are being created and look correct - to avoid any regressions

[dmah42]

I think I should maybe break this PR into multiple, because the diff doesn't make it super obvious now what is:

• moving docs around - to be able to more easily generate them and avoid duplication and keep them in sync
• drift between committed and generated docs - which shouldn't be a problem if we don't commit any generated docs
• making sure our generated docs are being created and look correct - to avoid any regressions

i'm happy with it in one PR if you are. i can follow along i think.

[bailey-coding]

i'm happy with it in one PR if you are. i can follow along i think.

I think the diff was confusing at one point for me, because I hadn't committed everything, and there was a bit of drift on my local machine, but I'm less paranoid now, after re-generating it all and navigating through the generated docs!

[krisnova]

ping -- is this ready for review?

[bailey-coding]

Sorry, needed to fix some stuff on my machine before I could test it one last time. I'll fix the conflicts, then I think it should be all ready for review!

[bailey-coding]

Sorry, life has been a bit hectic. I'll update this PR this week!

[krisnova]

Closing in favor of #459