User talk:Red Leader/Nasal documentation proposal

integrating your Nasal docs with the Python script

I am not sure whether you are aware of it or not, but there is actually a Python script to extract /some/ information semi-automatically from the base package and create the corresponding docs, I think it was Adrian (?) who once created it (not sure though). In its current form it provides HTML (IIRC), but it should be easy to adapt/extend to also support mediawiki markup, and it already parses some common "doc-strings", and given your Python work on the Nasal/pygments lexer, it may actually be worthwhile to explore adapting the script to directly make it output the required markup for the more common modules, so that most of these docs could be committeed to the base package (and/or the corresponding Python script), so that the script can be used to help update the wiki docs (imagine renaming an API, or moving it to a different namespace).

For some additional background info, see:

• https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/scripts/python/nasal_api_doc.py
• https://forum.flightgear.org/viewtopic.php?f=30&t=15133&p=148751&#p148751
• https://forum.flightgear.org/viewtopic.php?f=72&t=25119
• https://forum.flightgear.org/viewtopic.php?f=71&t=19259&p=178185&#p178185

As far as I remember, that script should be part of the repositories by now - and it should be much less work to teach it outputting mediawiki markup, than duplicating its work here, especially in the light of future $FG_ROOT/Nasal changes, which would inevitably mean that the wiki docs would be out of date. Thus, my recommendation would be to see if the script still works, and if it is feasible to make it output mediawiki markup (if in doubt, using a handful of custom helper templates) and then incorporate some/most of the info you came up with here, so that the script can then be used to update these articles semi-automatically - we can probably also get a little help/feedback from bugman, who's also been interested in wiki matters, and FlightGear scripting in particular, and who's got a pretty remarkable Python background, too.

Also note that bugman recently mentioned a related idea on using svn hooks to automatically update wiki contents:

"I would prefer to write a small script that auto-generates a Mediawiki-formatted table from a FGAddon checkout (unfortunately my Python interface into the FG/simgear core is not up to the job yet, so I migt need to use XML parsing). Then we could have a wiki page that shows what is left to do. I can then link to this via the aircraft infobox for aircraft missing the new ratings. I have seen that the wiki aircraft pages sometimes includes the new rating system when the aircraft *-set.xml file does not, but I do not know how reliable those ratings are as they were not pushed into the repository."

--Hooray (talk) 16:17, 6 September 2016 (EDT)