Add Docs Site

[michaeltlombardi]

Is your feature request related to a problem? Please describe.

When I want to show my coworkers how to use dash, I have to send them to the README, which is written for people who are already comfortable writing YAML configurations and willing to work through things on their own.

Describe the solution you'd like

I'd like to be able to point my coworkers and the people who get interested in this tool to a small docs site that has some narrative documentation for using the tool as well as reference documentation for
the configuration options.

Describe alternatives you've considered

Instead of a docs site, we could maintain a folder of Markdown documents in the repository.

Additional context

My day-job is documentation. I'd be happy to draft some initial documentation and help out with it in the long run.

[dlvhdr]

This is a great idea, and I appreciate the help 😃

Off the top of my head, I heard good things about docusaurus

[dlvhdr]

After checking out docusaurus it does seem like a good option. I can just create a docs dir in the repo and put the site in there. That way the docs and the actual code don't go out of sync. Also, seems like a popular option.

How would you imagine the docs site being different from the README? The README did get a bit too big so breaking it down will definitely help. Any other benefits?

[dlvhdr]

I've created a docs branch with the docusaurus template. Feel free to contribute there and once it's ready we'll release a version. #261

To start working on it you should:

cd docs/website
pnpm install
pnpm start

[michaeltlombardi]

I should've commented sooner, I have a local working branch using Hugo that also includes full documentation for the configuration schema and the dashboard commands. I'll get that up early next week and we can either port things over to your branch or keep using it, whichever.

The docs (and schema) are fully contained in the docs folder so it's easier to keep everything up to date. I hand-crafted all of it initially, but I'm sure long-term we could figure out a way to automate/regenerate some or all of the reference information from the code.

[michaeltlombardi]

How would you imagine the docs site being different from the README? The README did get a bit too big so breaking it down will definitely help. Any other benefits?

The biggest benefit to my mind is that there's too much to document in the readme and the information architecture for a single document is too limited.

With a docs site, you can clarify the configuration options and dashboard commands more fully, give more and longer examples, and people can link directly to the information they need and consume it at a level that they can retain.

[dlvhdr]

No worries, I haven't done much. I've heard good things about hugo but don't know how it compares to docusaurus in terms of fitting to the docs use case. But, I don't need to be strongly convinced either. I'm also down for using the same language. I'll do a bit of reading nonetheless

[michaeltlombardi]

I have a slight preference for Hugo because I've used it for ages (for docs and non-docs sites alike), but I don't think it makes a huge difference in the long run.

The branch I have is using a Hugo module I maintain for using YAML files as the source of truth for their documentation and cleans/composes them into JSON schemas published on the site, but I will probably end up turning that functionality into a standalone binary too at some point.

The rest of the documentation is just Markdown with some convenient markup handlers I wrote for things like key combinations and using Shoelace components for alerts, icons, etc. But the content itself is entirely transferrable to any given tooling.

[michaeltlombardi]

This is a quick preview of the WIP. Still working steadily on it.

gh-dash-docs.mp4

• Getting Started
  • Installation
  • Usage (command line docs)
  • Keybindings (dashboard command docs)
• Configuration
  • Schema (main page)
  • PR Section (schema/info for defining an entry in prSections)
  • Issue Section (schema/info for defining an entry in issueSections)
  • Defaults
  • Layout - partially done
  • Keybindings
  • Theme
• Contributing

There's a few other things to do - I need to do some adjustments for accessibility, mainly, and consider not using firacode for prose (I was being lazy). I need to cleanup styling for schema pages.

We may want to add a UI section that explains everything happening in the UI, since the symbols are mostly self-explanatory, but aren't spelled out.

We will eventually want to have some tutorials, I think. Maybe us VHS to capture the commands?

An idea I had for later was a configurator - use alpine and shoelace to let folks build their own configuration for a dashboard. I think a live preview is out of reach, but being able to fill out options and download a configuration seems neat. Could also use a page where you can validate your configuration against the schema, maybe.

I'm kicking around a general purpose render hook for codeblocks with ANSI codes, which would let us display some of the elements in snapshot form directly in the docs site.

[dlvhdr]

This looks amazing! Thanks for all the hard work!

Regarding the font, yeah fira code might be a bit much for a site.
I recently discovered https://www.fontshare.com/ for free fonts which looks like a good site.
For my personal blog I'm using github's recently open sourced fonts - hublot and mona and I quite like them: https://github.com/mona-sans

Once the docs site is up I might work on a landing page. I always wanted an excuse to work on a nice landing page :)

I'm not familiar with alpine or shoelace so I'll check those out.
The most naive solution to easy configuration is to introduce "recipes" or something like that. Or maybe making the initial configuration be based on your most recent contributions if that's possible (a section for each repo you contributed or something like that).
A live preview is definitely the best in terms of UX.

Regarding the UI section, that definitely sounds like a cool use case for VHS.

[michaeltlombardi]

Recipes is a great stopgap idea. I've been leaning into those a bit for the schema examples, but a library of them would be great.

An overhauled landing page would be rad, what I have now is just a lazy snipping from the readme. 😅

I'll swap the normal body font to mona after I get the icons working (I need to use proper icons instead of what's there now - those icons are from the font, which makes them terrible for accessibility).

I think we might wanna keep firacode for the monospace since that's also what the example VHS uses (according to a readme note, at least).

Alpine is super convenient for adding interactivity to static sites. Shoelace is just a set of good web components.

I'm really enjoying working on these docs, it's been a blast!