On Wed, Aug 31, 2016 at 12:00:30PM +0200, Yuriy Tymchuk wrote: > Ok, now I know what I want. > > I want a better way to document. Because I’m trying to write a documentation > about my stuff, but there are too many disconnected ways to do that. I’m > trying to always have reasonable class comments. But sometimes you need a > more general description, so you write help topics which are disconnected > from class comments. Yes, we can add help topics generated from class > comments but that’s too weak. Additionally I version my projects on github, > so I want t doc there in readme, or on a wiki. What’s more I think that it’s > a good idea to export doc to the web. Because when someone mentioned package > manifest I started to google for it and could not find anything. > > My suggestions: > - write comments in pillar and slowly add pillar support to enrich comment > (documentation) styles > - add a possibility to reference classes/methods and help topics from pillar > comments > - have exporters to generate html documentation about a project based on > comments and help topics > - then I will be able to add a hook to Icebeg telling it: ok, on commit also > generate a doc and export it as MarkDown (because we can) and commit it as a > README or as a wiki entry or whatever. > > This way we will have interconnected documentation in the image, and if it > should be placed somewhere else we export it.
+14. Knowing that I cannot verify that the documentation is sync with code is very discouraging to even start writing the docs. When I was writing a chapter for agile visualization, I had the examples as independent scripts which I could execute (I believe Pillar has added executable examples since then). But there are more things than examples, e.g. a Travis could run "docs verification" that would look at all the code (so even method and class name references) and made sure they exist and are not, say, deprecated. As Pillar provides you with a real syntax tree this might not be so hard. At least personally the above could be a real value for me with Pillar, because up until now it was just another document format (and there's a lot of better ones) with poor infrastructure. But deep integration with Pharo could make it really valuable, and we are getting there. > - then I will be able to add a hook to Icebeg telling it: ok, on commit also > generate a doc and export it as MarkDown (because we can) and commit it as a > README or as a wiki entry or whatever. so close :) https://github.com/peteruhnak/IconFactory/blob/master/repository/BaselineOfIconFactory.package/BaselineOfIconFactory.class/class/updateReadme.st Peter
