In squeak by example we could tag in the document code snippet as text and a perl script turn the expression into Sunit method and run the tests We lost that. Stef Le 31/8/16 à 12:21, Peter Uhnak a écrit :
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/BaselineOfI...
Peter