help.lasso for Knop for Lasso 9

[stevepiercy]

In Lasso 8, we have this pretty nifty semi-automatic documentation of the Knop API and its types and methods.

http://montania.se/projects/knop/help.lasso

It's not fully automatic. We meticulously added all that information for each method as the value for the -description parameter. help.lasso parses the string, then formats it to look pretty. The output is nice, but the labor involved and potential for mistakes is not so much. Also it is not in a single searchable file (like a PDF) and it lacks a search feature (excluding in-browser searching, of course).

Thus we've been looking at better ways of documenting the Knop API for Lasso 9. Our goals are:

• Write source code once and parse the source for API documentation.
• Read a method's signature and return its parameters, traits, and other elements into a structure that can be easily parsed.
• Avoid use of -description, if possible.
• Use a simple markup language (like .rst) that can be parsed easily and output to HTML, RTF, plain text, or PDF.
• Generate a searchable index.

Essentially we're looking to create a Lasso domain for Sphinx.

http://sphinx.pocoo.org/domains.html

We're looking to collaborate with any developer on this effort. Please add your comments below.

[bfad]

Have you thought about utilizing Lasso 9's doc comments? Here's a quick example grabbing some doc comments in the Lasso 9 core code itself (Run this from the command line):

LASSO9_RETAIN_COMMENTS=1 lasso9 -s "with m in sys_listUnboundMethods where #m->docComment->size > 0 select #m->docComment"

[stevepiercy]

Thanks for the example. It is part of our consideration. This may be one piece of the overall puzzle. However it's pretty much the same as using -description, unless I am missing something.

I know that the use of javadoc syntax was tossed about years ago for auto-generation of documentation, but I have no idea what happened to that idea, whether it was abandoned or set aside for higher priorities within LassoSoft and never developed further.

[bfad]

It is like -descripiton but it gives you the ability to also document traits. My thought is that the doc comments would contain a simple markup language. I'm not sure if javadoc markup has been implemented or not, but if not, then that gives you the ability to use whatever markup you want.

On another note, in terms of getting method / type signatures in a programatic fashion, it looks like this may have some gems in it:
http://source.lassosoft.com/svn/lasso/lasso9_source/trunk/reference_generator.lasso
(Take a look at [reference_makeDecoratedMethodName], for instance.)

[stevepiercy]

Yeah, there is some good stuff in there, but a lot more questions. What is the bitTest method? How do we get the return type of a method?

Anyway, back to the point of what markup to use, we're discussing which is best. Markdown is simple and can be instantly previewed in BBEdit, but limited in features. ReStructuredText has a lot of flexibility and is easy to use, but requires an interpreter to render it to a given output (for which there are many options).

Javadoc may be another option. Here's some information on it.

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

[stevepiercy]

I've been doing additional research about which markup syntax to use going forward. I am convinced that the best option is ReStructuredText (one word or "RST") going forward. The reasons are:

• easy to use
• supports tables (markdown does not)
• widely supported
• GitHub can render RST files in repositories as HTML. See https://github.com/github/gollum
• pandoc can easily convert existing documentation to RST. See http://johnmacfarlane.net/pandoc/
• Using pandoc, RST can be output to numerous formats, including HTML and PDF.
• restview is a Python tool that enables one to preview RST in a web browser or BBEdit's Preview via HTML Web Sites without sending it through a processor, restview: http://mg.pov.lt/restview/
• Sphinx's primary input is RST.

[bfad]

I would be interested in helping to create a Lasso 9 domain for Sphinx. Have you made any progress on this? I'm starting to read through Sphinx documentation.

[stevepiercy]

Thanks to Brad, we've made significant progress on this issue.

https://github.com/knop-project/knop/tree/master/knop9/docs

I think we might be better off breaking this into different issues going forward and categorizing/tagging the issues as "docs".