Documentation Website v0

[dunkOnIT]

Overview of changes:

• The existing documentation website found at cubing.js/docs has been replaced with a Jekyll-based documentation website.
• As yet, no new documentation has been added - it is only populated with (sketchily) ported documentation from the existing cubing.js/docs website.
• There is a lot of technical detail to record around how the site has been set up and how it should be maintained - I am aiming to make this a priority entry into https://tydvirtaal.github.io/cubing.js/contributing/, so that the IP doesn't sit with me.

Purpose of PR:

• This is intended to show the functionality and layout of Jekyll + minimal mistakes theme, with the hopes of getting answers to the following questions:
  • Any questions or confusions that arise?
  • Any dealbreaker issues that you notice?
  • Are we happy to continue building out the documentation on this foundation? Or do we need to apply core stylistic changes/consider another static site generator?
• I was very deliberately AVOIDING the following:
  • New contributions to the existing documentation
  • Meaningfully iterating on the existing format/structure of documentation (I've really just thrown together a proof of concept)

Comments:

• There is definitely some scuff (especially in the API reference documentation - gross formatting of input/output, preview width sometimes too narrow for code snippets), but I'd argue not to address these now, as I would prefer to address them as part of a more holistic refactor of the documentation.

High priority next steps:

• Process documentation on how to update the website
• Investigate inclusion of TSDoc-generated API reference documentation

[rokicki]

This looks good to me. I'm going to let Lucas comment (he's the main boss). The only little nits I could see offhand were:

1. The GPL license (one place); I'd replace this with either just "the GPL" or with "the GNU Public License", since the L in GPL stands for license anyway. It's like saying "The El Camino" (which people do say).
2. There's something funky going on with font switches in links; the underbars get changed. I'd fix this by trying to see if leaving sites in the same bolding as the surrounding text preserves the underline height, or if that fails, consider just leaving sites in roman.

I'm excited by the work you are doing and can't wait to see it live.

[lgarron]

@dunkOnIT We discussed redoing this in JS; would you still have time/interest for that?

[dunkOnIT]

Responded to Lucas privately to advise that I'll be trying to get this tackled again, using a Javascript static-site generator ("SSG"). I have less time on a weekly basis to work on this than before, but will be trying to take steps forward each week.

During the week ahead, I'll hope to at least try out a Docusaurus deployment, and if all goes well then I'll replicate the Jekyll site in Docusaurus. Failing that, Hexo with the Docs template will be my second port of call.

Roadmap at present:

• [x] Brush up on HTML/CSS/JS knowledge
• [x] Shortlist alternative SSG's
• [ ] Test out (Docusaurus)[https://docusaurus.io/] as a docs solution
• [ ] If Docusaurus doesn't work, try out (Hexo)[https://github.com/hexojs/hexo]
• [ ] Once I have a working SSG, replicate the Jekyll MVP documentation website in it
• [ ] Once MVP is complete, automate the site's deployment using Github Actions

[lgarron]

Glad to hear it!

I think at this point I'd prefer to avoid Docusaurus since it's so heavily tied to react. If I had to pick something without further research I'd probably go for Vite, but Hexo does look more specific to the task!

[dunkOnIT]

Thanks for the tip, will take a look at Vite as well!

I was also worried about seeing React in Docusaurus, but kept going when I saw I could still provide it .md pages :P Is your concern that Docusaurus has a dependency on React? Now that I'm typing it out, I suppose if the site compiles to a React project, that makes it difficult to troubleshoot anything going wrong, so it puts it in the same place as Jekyll did :P

[dunkOnIT]

Progress on finding a Static Site Generator ("SSG"):

• Hexo works as an SSG, but doesn't seem to have a maintained/easily available documentation theme. There seem to be a few ways to get something going, but (a) most of my efforts were in vain/required a lot of troubleshooting, (b) we will only run into more dependency issues and deprecations, (c) trying to reverse-engineer another website's theme doesn't seem like a great time investment at this point, and (b) as time goes on.
• I looked into Vite, but it seems to be more of a Javascript bundler than a SSG? I'd imagine it could be used to create documentation, but I don't see currently how we would get it to the point where updating the documentation is as simple as creating a new .md file. @lgarron if you want to expand more on how you'd go about using Vite, though, I'd be all ears!

My next actions will be to explore the following options:

• Docsify (promising as it is natively built for documentation so themes shouldn't be an issue, possibly dependent on Vue - it definitely supports Vue in its templating but its not yet clear to me whether this introduces a Vue dependency
• 11ty (very simple and vanilla JS, but I don't see any documentation themes yet - although I've only taken a cursory look)

Question on avoiding dependencies/frameworks

I'm wondering if we're working harder than we need to in order to avoid dependencies/frameworks?

• Note: I'm writing all of this on the assumption that we would only ever generate documentation which uses normal markdown - even if we were using an SSG that gave access to templating via frameworks like React or Vue.
• If we find an SSG that works as it should, then the framework should be completed abstracted from anyone adding to the documentation. All they would need to do is add/edit Markdown files - so
• Frameworks also seem largely abstracted from someone "developing" the documentation (changing themes, structure, etc). With a well-supported/documented framework, all one really needs to do is install an npm package, change settings in yaml, perhaps copy theme-related files into the directory, and run commands to generate the static site (eg, hexo generate)
• In the worst-case, if a particular SSG proves to be untenable because of a dependency/framework issue, the friction to switch is minimal - all of our content is stored in normal .md files, and transferring them to another SSG is as simple as copy-pasting them into a directory, and possibly modifying naming conventions/file headers.

Now that I'm getting further down the list, I'm wondering if the more we look for something pure-JS, the more likely it seems that we end up with something that is outdated/not well-supported and that we need to do troubleshooting/template setup ourselves, when it otherwise would likely not be necessary.

[lgarron]

Thanks, @dunkOnIT! I think 11ty sounds the most promising of those — Markdown input (as long as we can still run JS to show players) + some sort of reusable menu mechanism are probably the only thing we really need for now.

[dunkOnIT]

Thanks for the response! Have tried with both Docsify and 11ty - Docsify was a dream, but unfortunately doesn't render the .md at html so getting javascript to execute from the documentation doesn't seem easy.

11ty seems like it will require more tweaking to set something with a navbar up. There is Spacebook, but it needs Node 12 and relies on Tailwind - which may be too much dependency for our purposes?

Next steps for me:

• [ ] Learn liquid/nunjucks and try to set up nav in stock 11ty
• [ ] Get Node 12 working and try spacebook

No need to weigh in on these posts unless you have comments you'd like to make - I'm finding them a handy way of tracking incremental progress/actions.

[dunkOnIT]

Most discussion has happened on Slack, but noting here that an MVP using 11ty is available at: https://dunkonit.github.io/11ty-test/

[debater-coder]

Have you tried Gitbook. It has support for Markdown and you can embed custom html.

[lgarron]

After talking to @debater-coder I gave API Extractor and TypeDoc a try.

API Extractor was rather difficult to set up, and generated 562 separate documentation files (one for each method), which was... not great.

TypeDoc seems to be promising, though: https://experiments.cubing.net/cubing.js-typedoc/

[lgarron]

At this point, typedoc seems to remain the most practical solution: https://experiments.cubing.net/cubing.js-typedoc/

If anyone has further thoughts, feel free to comment, else I'll probably see about moving the TypeDoc build to js.cubing.net and closing this issue.

[lgarron]

At this point, typedoc seems to remain the most practical solution: https://experiments.cubing.net/cubing.js-typedoc/

If anyone has further thoughts, feel free to comment, else I'll probably see about moving the TypeDoc build to js.cubing.net and closing this issue.

I've gone ahead with this: https://js.cubing.net/cubing/api/