Document auto-generation? Moving docs from wren to wren-cli?

[joshgoebel]

I'm currently looking into how to properly/better document wren-console and wren-essentials and it's been suggested to use doc comments that way the docs are more likely to stay up-to-date with code changes. I also know right now CLI docs are in Wren repository, which has been it's own problem:

• requirement to make two PRs for every API change
• docs becoming out of sync because of this issue

Is there any receptivity to moving the docs from wren to wren-cli and perhaps changing how this work to make things more automated? It's possible (if we had a workable plan) I could do some of the work here (benefitting CLI) and then port that work over into wren-console as it makes sense to do so...

So to be clear the two issues here are:

• Document auto-generation from comments
• Moving documentation source from wren to wren-cli

There are obviously separate, but clearly intertwined if we decided to do auto-generation, etc... since then it would be impossible for the docs to live outside this repository.

Thoughts?

[ruby0x1]

I don't think automatic generation is worth the effort at this point. The hand written docs are fine (since if you're changing an API, you should be updating the docs). Given the surface area and simplicity of what we have I'm not inclined at this point.

Moving the docs does makes sense. Here's what I'd do to start:

• copy the whole docs setup as is from wren -> wren cli
• refactor the content so that the landing page is the one at https://wren.io/cli/
• this makes the root page this one (with the same side bar)
• only the cli only modules come along too
• make sure there's good side bar links and landing page content to point back wren, and to wren modules

This should be relatively quick, and would be the starting point. A PR for the docs/ folder ready to generate.

We can put the output on github pages, and link to it from the wren side, once that's done, we'll automate it similar to the wren docs (which will be fixed soon, we'll do that at the same time).

[joshgoebel]

make sure there's good side bar links and landing page content to point back wren, and to wren modules

I'm not sure I followed this part... are there specific changes you're suggesting from the existing CLI sidebar? We could add "Wren Modules" in addition to CLI Modules... should all the links just stay the same?

I'm not sure if you're suggesting this live at a different URL if we're just going to fix the build process to generate both then throw them back in the same old pages folder as before?

[ruby0x1]

The idea is to move the cli docs out of the wren repo, and host it here, via github pages. That makes it it's own standalone site with it's own URL. This is simpler and cleaner and quicker. Then, we link to it from the wren.io page, and link back to wren.io. For the most part the links would look the same and work the same.

However, because the CLI page is now it's own landing page (and not a subset of the wren home page per se), we can add a sentence or two about Wren with a link back (on the content) and links back on the side bar, to make sure the Wren api docs are easily found.