gakimball/spacedoc

🚀 Futuristic documentation generator

Spacedoc

A fancy documentation generator that can mash up documentation from multiple sources, such as SassDoc and JSDoc. Spacedoc was originally forked from Supercollider, the documentation tool used by the Foundation family of frameworks.

Features

• Combines Markdown, SassDoc data, and JSDoc data into compiled HTML pages.
• Supports custom Markdown and Pug instances.
• Can generate a search result list out of documentation items.
• Can be extended to support other documentation generators.

Documentation

Read the overview section of the documentation to get an overview of how Spacedoc works. Then check out the full documentation.

Local Development

git clone https://github.com/spacedoc/spacedoc
cd Spacedoc
npm run bootstrap
npm test

Repo Structure

Spacedoc is a monorepo powered by Lerna. This means all of the library's core packages are maintained here in the same repository, and published as separate modules using the same version numbers.

The packages include:

• spacedoc: core library.
• spacedoc-helpers: template helper functions.
• spacedoc-js: JSDoc adapter.
• spacedoc-sass: SassDoc adapter.

spacedoc's Issues

GitHub Repo Adapter

Global mixins for adapter templates

Navigation customization

There are many ways a developer might want to structure the navigation of the site. Of course, we could make them type it all out manually, but where's the fun in that?

Potential options:

• Flat list of pages
• Grouped by folder
• Grouped by group metadata
• Flat or grouped pages with custom ordering
• Some pages/folders are excluded from nav
• Nav from other packages inserted

SassDoc adapter

init() returns a Promise when used outside of Gulp

Consume Docs from Other Repos

Switch to markdown-it

Search Bar Plugin

apiDoc Adapter

Refactor Pug globals

• Page stuff -> page
• Template globals -> template

Add consolidate.js support

Fix path issues in generated links

Links generated for final HTML pages aren't consistent in how they handle relative and absolute paths and such.

Auto-generate search result hash

Prettier console errors

Hexo plugin

Exclude/include pages in nav

CLI module

Page ordering in nav

JSDoc Adapter

Default Layout + Theme

Simplify logging

Something like this:

File changed: pages/index.md
Parsing 1/1 pages...
Building 1/10 pages...

Override templates per-page

Internationalization

Page Groups

Incremental builds

Incremental builds were removed in eb74574. Here's a better way to implement them:

• When a page changes, only re-parse that page, and replace it in the tree.
• Then build every page again.

File watching in CLI

Embed Adapter Data Anywhere in Page

Watch source files linked to a page

Re-compiles of the static site are only triggered when a page changes, not when a source file linked to a page changes.

Ideally, changing a source file only re-compiles pages linked to that file. Search results are also re-compiled.