search

lsms-worldbank / doctools

MIT License
0 stars 0 forks source link

sthlp : see if MakeDoc can create help files when documentation is in head of .ado file #3

Open arthur-shaw opened 1 year ago

arthur-shaw commented 1 year ago

More for completeness than anything, see if MakeDoc can generate help files from documentation in the head of the ado file--for example, as here.

Files to produce:

Methods for producing:

kbjarkefur commented 1 year ago

I have been able to produce sthlp and markdown from documentation in the ado. My experiment is in 87a88a70591ba168b048a05dd75b6dba70dd2c1f.

While it works, I think the trad-off of making it more complicated justify the benefits. See reasons for me being of that opinion and more details from this experiment here: https://github.com/lsms-worldbank/doctools/tree/main/stata-doctools/sthlp-outlet/markdoc-ado2smcl

kbjarkefur commented 1 year ago

I have not tested it in pandoc as it works well in mini and my Stata does not find pandoc.

arthur-shaw commented 1 year ago

Thanks for looking into this!

I tend to agree with your conclusions. For Stata users, the workflow is already to write documentation in separate files. From that perspective, the ability to write in-line documentation is only convenient/familiar for R/Python users. Also, I'm one of those Stata users that loves the type of comments that would cause problems for MarkDoc. To the extent that ado files are complex, perhaps others will use those types of comments too.