jacobrask
Option for custom templates
Hi,
In the 0.6.x release, the option of custom resources (-s) disappears. In my particular case, i use this option for customize the template of the generated documentation (the docs.jade file) with some mayor changes (for example, other navigation, styles, etc).
I understand that the option overwrites core files of styledocco (like scripts or styles), but, in the other hand, the posibility of overwrite the template gives more flexibility to the app. So i think it would be a good idea add a option for custom templates (like -t docs.jade).
Regards
The reasons I removed it were:
- I wasn't sure if anyone was using it
- I prefer good defaults (and forking) over extensive configurability and endless options
- I was afraid of having to spend time on bug reports from people who had customized their resources, instead of improving the default experience
That being said, I am now working on a new way of including the static resources. Everything will be done from within the template instead of in StyleDocco, so to replace all the things you'd only need to use a different template.
The client side scripts are also modular, so you could potentially leave out the file which controls the UI (dropdowns, search) and only include the one which generates the preview iframes.
Issue #3 above is still valid though, but I might add it as an option without documenting it prominently in the readme.
Thanks for your feedback and for helping make StyleDocco better!
Wondering what the status is on this issue. Am able to hot swap the doc.jade and doc.css, but that is not ideal for distribution. Any way I can help?
- I wasn't sure if anyone was using it - Everyone was! Give it back please
@kristoferjoseph I've taken over maintenance of the current release. I can see @jacobrask's reluctance to support this feature. If we provide a switch to the user, I feel we should be able to support it. We can't support templates we don't know about.
That said, I like the idea of providing alternative themes at least to the extent of colour schemes. What were you using this feature for?
I think we can make this work by publishing to a view object and supporting a default template. If a user is using his own custom template, we can still support his bug request so long as he can provide a dump of the view object. If the view object is correct, then it's not our problem.
#78 seems related
Instead of waiting for this we went ahead and created Topdoc Allows you to use a flexible yaml commenting style as well as custom templates.
+1, it's now a year ago :(
Well, it's just me working on it and it's not my only project. I welcome patches if you want to help out. Please add new functionality against the dev0.7 branch. If you've got any questions, please ask.
Incidentally, a lot of the work in that branch is with this issue in mind, so it hasn't been forgotten about by any means.
Judging from https://github.com/jacobrask/styledocco/blob/dev0.7/src/gather.js on dev0.7 we could simply add a resourcesDir option. Reading the discussion above this sort of option has been removed though. So it seems wrong to simply readd it.
@marrs, since you are the only person working on this, what would you suggest:
- Add
resourcesDiroption back in. - For starters simply add a
templateoption for referencing a custom.jadetemplate.
Is this workable? What do I need to do here to get this going? I have sort of settled on styledocco, but without being able to modify the template I will look into retrofitting dgeni/ngdoc for sass. I don't want to do that if the custom template option is feasible with styledocco.
I just went in and edited my version of styledocco (inside node_modules) to pull in a custom template.
@tilomitra You should consider forking the project and submitting your changes as a pull request.