Proposal: Restructure Janet's Documentation

[CFiggers]

This PR proposes restructuring janet-lang.org's documentation by creating two (2) new top-level sections, one (1) for jpm and the other for Spork.

Rationale

The recent decisions to include function references for Spork and jpm on janet-lang.org make sense to me, both from an ease-of-maintenance and ease-of-discovery standpoint. However, the current integration is not ideal.

Regarding jpm: The main body of documentation for jpm is in a single (decently long) page under the Documentation section. Separate from that page, there's also the recently-included grouping of jpm API references under the API section. In my opinion, the jpm-related pages—explanatory docs and api references—should live close together rather than being split up. In fact, on reflection, the page about jpm under the Documentation section is a bit of an oddball compared with the rest of the pages in the section. The other pages all have to do with the syntax, semantics, and key concepts of the language itself. Jpm, while important in practice, is not technically speaking a part of the language itself (and is even decreasing in critical importance with the introduction of the bundle/* functions to the core library). And on top of that, because of the large amount of ground that one page has to cover, that page is on the longer end of pages on the current site—it could easily (indeed, I feel it should) be split into multiple pages for easier indexing in order to make its contents more visible in the overall site's ToC.

Regarding Spork: Currently, because there are more individual modules for Spork than there are individual modules in the core library, the Spork docs visually overpower the core API's module pages. On my laptop at the default zoom level, Spork module pages alone take up an entire screen from top to bottom, meaning the first couple of core modules are distantly separated from the last few (by more than a screen height, in my specific case, so it's not even possible to visually inspect the full list of core modules without scrolling). This is not beginner-friendly. Most beginners need to familiarize themselves with the language's core functions and macros (i.e. answering the question "What does this language have in it, anyway?") before venturing into the "expanded core lib" that Spork is shaping into. (The main API page containing all functions is still perfectly accessible, of course, but speaking from my own experience the list of module pages is still a helpful tool for discovery of the core library's contents.)

Summary of Proposal

To fix both sets of issues outlined above, I propose that we:

• Create new top-level sections for jpm and Spork
• Move the documentation on jpm that currently lives under the "Documentation" section into the new JPM section and also split it into multiple pages for easier reference (there are new sections on that page that I didn't realize had been added until I was going through this exercise!)
• Move the API references for jpm and Spork into their respective newly-created sections
• Bring over the newly-revamped documentation now published under janet-lang/spork/docs
• Rename the current "API" top-level section to "Core API" to distinguish it from the jpm and Spork "API" sections

I think this pattern has a number of advantages:

• The "API" (now "Core API") section is much, much cleaner
• This way there's a natural spot to put article-length explanatory documentation pages related to jpm/Spork (I think under Spork we need a) more reference documentation on CJanet and b) some clearer Contribution guidelines, as an example)
• Examples and explanations that currently exist only in janet-lang/spork/docs are now consolidated here (and we can go ahead and remove the doc/ directory in janet-lang/spork if we want to without losing anything)

Points of Feedback requested

Point 1: I added the new "JPM" and "Spork" sections after the "C API" section. We could also prefer putting that section at the very end.

Point 2: Stylistically, I think it's cleaner not to have the spork/ prefix on all functions on the top-level Spork API reference page. I tweaked the import to eliminate that. But on the other hand, if one were to merely (import spork), the double-namespaced forms are what would appear in the REPL. Please let me know if you have strong feelings about this.

Point 3: On review, it looks like as part of this PR I also added a module page for janet/* bindings in the Core API section, since those (three whole bindings) were not showing up anywhere other than the main index page. That could potentially have been a separate PR—let me know if you'd like to revert that piece here.

[CFiggers]

For anyone who's never built and viewed the janet-docs.org website locally before, you will need make and Mendoza installed (grab the latter with [sudo] jpm install mendoza). Once you have both, run $ make and then $ mdz serve in the project root (either the current master or in this PR after cloning it locally if you want to see my proposed changes). You can then view the compiled site at http://localhost:8000 as long as the mdz serve process is running.

[pepe]

I see these changes as progress in the right direction.

I would love to see it leave Mendoza in its current form. We have all the pieces in the core and the Spork.

[sogaiu]

Overall I like the proposal. Thanks for your efforts on this.

Point 1: I added the new "JPM" and "Spork" sections after the "C API" section. We could also prefer putting that section at the very end.

I think the current arrangement makes it clearer that jpm and spork are separate from janet and I prefer that.

Point 2: Stylistically, I think it's cleaner not to have the spork/ prefix on all functions on the top-level Spork API reference page. I tweaked the import to eliminate that. But on the other hand, if one were to merely (import spork), the double-namespaced forms are what would appear in the REPL. Please let me know if you have strong feelings about this.

At least under the index, not having the spork prefix does seem less cluttered.

I'm not entirely sure it's a clear win, but leaving the prefix has the downside mentioned above.

It doesn't appear to be consistent with the current state of the jpm stuff though (at jpm/api/index.html). To spell that out a bit, under "Index" I see links starting with:

jpm/cc/archive-c jpm/cc/compile-c jpm/cc/create-buffer-c jpm/cc/create-buffer-c-impl jpm/cc/create-executable jpm/cc/embed-name

Would consistency be worth considering?

[CFiggers]

Point 2: Stylistically, I think it's cleaner not to have the spork/ prefix on all functions on the top-level Spork API reference page. I tweaked the import to eliminate that. But on the other hand, if one were to merely (import spork), the double-namespaced forms are what would appear in the REPL. Please let me know if you have strong feelings about this.

At least under the index, not having the spork prefix does seem less cluttered.

I'm not entirely sure it's a clear win, but leaving the prefix has the downside mentioned above.

It doesn't appear to be consistent with the current state of the jpm stuff though (at jpm/api/index.html). To spell that out a bit, under "Index" I see links starting with:

jpm/cc/archive-c jpm/cc/compile-c jpm/cc/create-buffer-c jpm/cc/create-buffer-c-impl jpm/cc/create-executable jpm/cc/embed-name

Would consistency be worth considering?

I would think so! Thanks for the suggestion. Just pushed a new commit for that.

[bakpakin]

I had almost forgotten that we still rely on mendoza at this point - my usual interaction with the documentation is editing individual pages, runing make, make run, and running ./update-janet.

I agree that the whole website lacks some polish, and the focus was more on creating a system that ticked all the boxes I had in mind - auto-generated, some styling, syntax highlighting, easy to add prose to, versioned documentation, and searchable. While we've accomplished all of this, there is a lack of documentation per function beside docstrings, styling is simplistic at best, and internal linking is sparse. And of course, organization for spork and JPM are strange.

Things are the way they are so that I could most easily reuse the code for documentation generation. Happy to accept PRs to reorganize things a bit.

[CFiggers]

Happy to accept PRs to reorganize things a bit.

That being the case, do you have feedback on this one?

[CFiggers]

@bakpakin I'd like to re-draw your attention to this PR, if I may. I think this would be a significant improvement to the organization of the Janet API docs and would also lay a strong foundation for future expansion.