Documentation

[sevki]

Hey Folks,

IMHO our documentation is really lacking.

Most of the docs are outdated and the code ya'll write isn't as legible as you'd like to believe 😂

I really miss docs experience whenever I'm writing go or rust code and it's making me want to not touch harvey code all that much.

So let's do something about it!!!!

What my current thinking is patch build.go to generate compilation DB.
Harvey-OS/go#35

this generates a compile_commands.json under $HARVEY

Once we merge that in we can modify the CI to pull the harvey-os.github.io repo

git clone [email protected]:Harvey-OS/harvey-os.github.io.git

after which we can generate markdown files for C code using clang-doc

clang-doc --output=harvey-os.github.io/docs/ --format=md -p=. --project-name=harvey --repository=https://github.com/Harvey-OS/harvey/blob/main/ ./sys/src/

than commit and push the docs to the repo so every time we update our code the website and docs reflect the changes.

What do ya'll think?

[orangecms]

Absolutely, didn't even know about clang-doc - that's fantastic! \o/

[sevki]

Ha. Neither did I!

I was just googling libtooling doc generator assuming someone would have written one. I was right!

Since the comment style is doxygen and none of our code (except for some apica code) is commented in that style the MD files it generates right now doesn't seem all that useful Harvey-OS/harvey-os.github.io@master...sevki:master

but I think it's far better than no documentation at all.

[gmacd]

Looks interesting. Would this only be used by the ci?

[sevki]

it wouldn't be exclusive to the CI. no reason why you wouldn't be able to generate docs manually and push them

but practically speaking I don't expect we'll start getting vigilant about docs overnight so IMHO CI should be in charge of keeping our docs up to date

[gmacd]

Looks worthwhile. Slightly unrelated, but it would be great to get the man pages up on the website too, maybe convert them to md 😀

[sevki]

TOTALLLYYYY!!! I don't think it's unrelated at all

I have a MD to troff converter here which is compatible with plan9 troff macros so after we have the MD files we can convert them back to tr than generate the pdf and man pages with the 9 tooling

[fhs]

Agree on the man page. Some of the kernel internals are documented in man pages in Section 10 in Inferno and Section 9 in 9front. Maybe we can copy and update those.

[sevki]

YES PLEASE!!