Hi Scott I’ve also been thinking about something similar: using TW5 to create a reusable tool that interleaves documentation files in a standard git repository, threading them together to construct a TiddlyWiki that can be used to view/edit the docs, or to generate static renderings. I think the round trip editing could be a killer feature: most existing documentation-baking tools expect editors/writers to navigate the source tree of MD files directly.
To your specific question about whether the documentation files might be sliced into multiple tiddlers as part of the process of threading them together, I suspect that that might make it a little bit harder to make a round trip editor. There’s also the question you raise about whether chunking into sections will actually lead to reusability. Perhaps there’s more scope for reusability by centralising definitions and descriptions, and transcluding them at the point of use? Anyhow, it’s all quite ambitious, but one could build it in stages: * An MVP to get things started might be a tool that scans a repo for documentation files and does the most basic aggregation of those files as tiddlers into a TiddlyWiki that includes a plugin containing the templates needed to view and interact with those tiddlers * Next, one might try to get things working under Node.js so that the documentation files can be edited within TiddlyWiki. There would be a startup process reading the tiddlers from the repo, and then passing them to the syncer/filesystemadaptor so as to have future changes to those tiddlers synced back to the original file * Finally, one could explore reusing some existing open source documentation templates for output Best wishes Jeremy > On 28 Sep 2018, at 21:21, Scott Sauyet <[email protected]> wrote: > > I'm working on a new programming library and want to generate a tiddlywiki > version of the documentation to serve from Node. I'm looking for advice on > the best way to do this. I will be maintaining the documentation in a > markdown-file-per-function format; this will work well with our GitHub > environment. I will need to convert that to tiddlers. I'd like to break > this down into smaller parts in keeping with the TW philosophy, But I don't > know if I should do this in some server-side build step or whether it would > be straightforward to do that inside the TW client environment. > > I will be doing this conversion in JS. Either it will take place in a > Node-based build step or in a custom plugin vaguely similar to the Markdown > plugin. So the core code would probably be similar either way. I know > little of plugin development., but I'm more than willing to learn. And if I > can manage it, I would much rather have the intact content (with just some > field headers prepended) passed down to the client and interpreted there. > But I just don't know how possible that is. > > The project is behind a corporate wall, and I can't share it, but it's > similar to work I've done on the open-source Ramda (https://ramdajs.com/ > <https://ramdajs.com/>). Taking a function like `map` > (https://ramdajs.com/docs/#map <https://ramdajs.com/docs/#map>), I would > start with this (sorry fairly long) markdown: > > ====================================================================== > > R.map > ===== > > *"It is not down on any map; true places never are."* - Herman > Melville > > Signature > --------- > > map :: Functor f => (a -> b) -> f a -> f b > map :: (a -> b) -> [a] -> [b] > map :: (a -> b) -> {String : a} -> {String: b} > map :: (a -> b) -> (r -> a) -> (r -> b) > > > Description > ----------- > > Takes a function and a [Functor][fu], applies the function to each of > the functor's values, and returns a functor of the same shape. > > Ramda provides suitable map implementations for `Array` and `Object` > and `Function`, so this function may be applied to `[1, 2, 3]`, to > `{x: 1, y: 2, z: 3}` or to `n => n + 1`. It delegates to other > Functors. > > > Symbolic > -------- > > R.map(f, [a, b, c]) //=> [f(a), f(b), f(c)] > R.map(f, {x: a, y: b, z: c}) //=> {x: f(a), y: f(b), z: f(c)} > R.map(f, g) //=> (...args) => f(g(...args)) > R.map(f, functor) //=> functor.map(f) > > > Examples > -------- > > * const double = n => n + n > const square = n => n * n > > R.map(double, [1, 2, 3]) //=> [2, 4, 6] > R.map(double, {x: 2, y: 3, z: 5}) //=> {x: 4, y: 6, z: 10} > R.map(double, square)(3) //=> 18 > > > * const increment = n => n + 1 > > R.map(increment, Maybe.Just(42) //=> Maybe.Just(43) > R.map(increment, Maybe.Nothing() //=> Maybe.Nothing() > > See Also > -------- > > - R.transduce > - R.addIndex > > Since > ----- > > v0.1 > > [fu]: ../types/Functor > > ====================================================================== > > > And I would like to generate a tiddler such as > > ====================================================================== > created: 20180928141411712 > modified: 20180928170503224 > tags: > title: R.map > type: text/vnd.tiddlywiki > > {{$:/api/R.map/intro}} > > !! Signature > > {{$:/api/R.map/sig}} > > !! Description > > {{$:/api/R.map/desc}} > > !! Symbolic > > {{$:/api/R.map/symb}} > > !! Examples > > <$list filter="[tag[fn-Example]tag[R.map]]"> > <$transclude field="text" mode="block"/> > </$list> > > !! See Also > > {{$:/api/R.map/seeAlso}} > > !! Since > > ``` > v0.1.0 > ``` > ====================================================================== > > > and a collection of supporting tiddlers like > > ====================================================================== > created: 20180928141421990 > modified: 20180928170615408 > tags: R.map fn-Signature > title: $:/api/R.map/sig > type: text/vnd.tiddlywiki > > ``` > map :: Functor f => (a -> b) -> f a -> f b > map :: (a -> b) -> [a] -> [b] > map :: (a -> b) -> {String : a} -> {String: b} > map :: (a -> b) -> (r -> a) -> (r -> b) > ``` > ====================================================================== > > > > > I guess the first question is whether a plugin's code can be run at startup > against a collection of tiddlers and generate more tiddlers. If that can't > happen, then I'm pretty sure I'm stuck doing this in Node. > > But then, if I can, *should* I? I really like both TiddlyWiki's > small-content-is-better philosophy and the single-markdown-file-per-function > documentation style. Perhaps I need to live with just the one and include > these simply as Markdown tiddlers. That would mean that I don't get the > ability to reuse smaller parts of the documentation in other interesting > places. But I don't have any immediate need to do that. It's purely > speculative. And yet, if I simply put it off, it probably won't happen. I > have time now to work on this that I probably won't get later. > > So I'm looking for advice. Would you do this in a server-side build step? > Would you do it inside TiddlyWiki? Is there some better approach I'm not > even seeing? > > Thanks for any suggestions you might have. > > -- Scott > > -- > You received this message because you are subscribed to the Google Groups > "TiddlyWiki" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected] > <mailto:[email protected]>. > To post to this group, send email to [email protected] > <mailto:[email protected]>. > Visit this group at https://groups.google.com/group/tiddlywiki > <https://groups.google.com/group/tiddlywiki>. > To view this discussion on the web visit > https://groups.google.com/d/msgid/tiddlywiki/09b73b62-4cbd-4316-9398-02d70b213643%40googlegroups.com > > <https://groups.google.com/d/msgid/tiddlywiki/09b73b62-4cbd-4316-9398-02d70b213643%40googlegroups.com?utm_medium=email&utm_source=footer>. > For more options, visit https://groups.google.com/d/optout > <https://groups.google.com/d/optout>. -- You received this message because you are subscribed to the Google Groups "TiddlyWiki" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/tiddlywiki. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/302716CA-52BE-4E4E-A2A0-F27614E88230%40gmail.com. For more options, visit https://groups.google.com/d/optout.
