We need a documentation system. Thought a lot about using the Sphinx documentation tool, which is quite nice, but having it in the database means we can do more powerful stuff like in-app integration etc.
Design thoughts:
Probably tie it to a bundle, so that bundles can contain their own documentation.
Pretty much any row in the database can be documented.
There are different levels of documentation here. A widget's documentation might be a) developer documentation for how to reuse the widget, how to call it, etc., or b) user documentation for how the feature this widget contains is used. We should probably just focus on a, developer documentation, at this time, and possibly have a totally different scheme for in-app docs, when documenting, say, the IDE.
It would be really nice to be able to auto-generate documentation stubs for say an entire schema
Need a way to distinguish between "public" and "private" functions, tables, views, types, etc. Not all functions are meant to be user-facing
Until bundles contain meta-entities, there's a kind of mismatch here, because there's stuff in the extension (currently almost everything), and there's stuff in the core extension's bundle (currently almost nothing). We want to be forward-thinking about this stuff since bundles containing meta-entities in bundles are coming soon.
We could use markdown. There are some nice Javascript markdown libraries, leaning towards markdown-it
Keep an eye towards integrating this documentation into the UI somehow
Tying this to the database schema is only one framing. We're going to want to be able to layout docs in an arbitrary way
Linking to a particular piece of documentation by name and potentially using an extended Markdown syntax that supports auto-linking would be cool -- we need what Django would call a "reverse"
Perhaps setup a dynamic template route like /docs/{ bundle }/{ slug }
We need a documentation system. Thought a lot about using the Sphinx documentation tool, which is quite nice, but having it in the database means we can do more powerful stuff like in-app integration etc.
Design thoughts:
/docs/{ bundle }/{ slug }