Open joshgoebel opened 2 years ago
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:
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).
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?
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.
I'm currently looking into how to properly/better document
wren-console
andwren-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:Is there any receptivity to moving the docs from
wren
towren-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 intowren-console
as it makes sense to do so...So to be clear the two issues here are:
wren
towren-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?