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/BaselineOfIconFactory.package/BaselineOfIconFactory.class/class/updateReadme.st
Peter
