[Docs] Carp website vs. Carp docs vs. Current repo doc setup

[scolsen]

The Carp docs are currently a bit scattered, we have:

• The docs in this repo docs/ which include core lib generated documentation and language docs.
• The docs in the carp-website repo, which power the carp website, which copy over some of the docs from this repo
• The docs in the carp-docs repo, which are a WIP migration of the generated docs from this repo into that repo (related to #607)

I think it'd be beneficial to settle on a single approach and to migrate all documentation to a single source of truth. Here's what I would propose:

Copy/Move all documentation related things into carp-docs including:

• Everything in the docs/ folder in this repo
• The autogenerated core lib docs
• The existing html of the carp-website

We should then set up that repo as a github pages site, and point it to some nice short url people can remember easily, such as carp.github.io, carp-lang.github.io, or, if we want, some vanity url like carp.org.

We should also setup the copying CI as mentioned in #607.

I think the docs/ folder contents can be either moved or copied. We could decide to restrict the documentation in this repo to docs about working with/modifying the compiler, and maintain all language related docs in carp-docs, or, we could just auto-copy things over...it is kind of nice to have the documentation available directly when you check out this repo.

Another approach would be to delete the carp-website and carp-docs repos and just maintain everything here in a docs folder. It would make this repo bigger, but it would also keep things simple.

[jacereda]

I think we should differentiate what's a source and what's a product. AFAICS the problem right now is that we're versioning products and that's a no-no. I wouldn't mind having everything in the main repo as long as there're no versioned products.

[eriksvedang]

Very much agree that this is a mess right now :)

I like all the suggestions, merge:ing carp-docs and the website makes a lot of sense (are you OK with that @hellerve ?)

I agree that it's nice to have the docs included in the repo but if we make the link obvious I think it's almost as user friendly to have them be on a separate site. And of course keep the implementor/hacking docs in the compiler repo.

The (help) feature in the REPL could then just have links to these various places.

[hellerve]

That’s totally fine with me; I haven’t had much time for the website since its original version TBH, and I think that’s a real shame! (I’d be happy if someone takes over)

[eriksvedang]

I’m taking a stab at automating the copying over of the docs to a separate repository (carp-lang/carp-docs). Will remove generated docs from main repo once it works.