Hi Lorenzo, about the patch, the scripting-related-part looks fine, Dick, you outlined the scripting-doc problem perfectly.
I think that after C++->swig-->py the C++ doxygen info could be recovered back into python pydoc information, and then back into another (scripting only) doxygen, then that could be extended with examples / tutorials. I've seen some scripts that did the trick (as far as I remember they parsed doxygen XML output and reinjected into .py as pydoc, but not sure now). I will put this as my next task as soon as I'm back, but if anyone finds motivation to do it from now to 29th then it's more than welcome :-) Greethings 2012/8/22 Dick Hollenbeck <[email protected]> > On 08/21/2012 06:35 PM, Wayne Stambaugh wrote: > > On 8/21/2012 12:30 PM, Lorenzo Marcantonio wrote: > >> On Tue, Aug 21, 2012 at 11:17:28AM -0500, Dick Hollenbeck wrote: > >>>> Pydocs or Doxygen or _________. > >>>> > >>>> This is what keeps us from getting lots of questions, or asking them. > >>> Although the infrastructure that Miguel is thinking about would apply > here too. > >>> > >>> He wants those docs on the website, and I agree with him. > >> Just decide the format at least:P 99% is explained in the demo script > >> but there are 'interactions' which will behave strangely (mostly those > >> disallowed from the plot dialog). > >> > > Doxygen supports Python so there may be some merit in using the current > > Doxygen infrastructure already built into KiCad. You can do a lot of > > interesting things with groups, sections, custom style sheets, etc. with > > Doxygen. I'm not sure if Pydocs has the same level of formatting > > sophistication as Doxygen. I would guess most KiCad developers would be > > more comfortable with Doxygen. That being said, I don't have a strong > > opinion one way or the other. What ever direction we chose, it should > > be as simple to generate the scripting documentation as it is to > > generate the current source documentation. In other words it should be > > fully supported by CMake when creating the build environment. > > > > Wayne > > > I think the key issues are these: > > > *) The scripting APIs will extend indefinitely, well beyond plotting. > > *) The person developing each respective API is best qualified to document > each respective > one. > > *) Swig generates code, and that generation process should not overwrite > documentation. > This puts a question mark on pydocs. > > *) Perhaps the best place for the documentation to be maintained is in the > swig source > files, *.i. This is scripting language neutral. > (I would not rule out using javascript as a scripting language in the > future.) > > *) Doxygen can be invoked on any number of configuration files, and those > control which > files are input. So it is sensible to consider a separate configuration > file for what > goes onto the website, because special css or formating is probable. > > *) Having a larger html footprint on the website puts out a larger net for > google, and > subsequently potential users. > > > > > > > > _______________________________________________ > Mailing list: https://launchpad.net/~kicad-developers > Post to : [email protected] > Unsubscribe : https://launchpad.net/~kicad-developers > More help : https://help.launchpad.net/ListHelp > -- Miguel Angel Ajo Pelayo http://www.nbee.es +34 636 52 25 69 skype: ajoajoajo
_______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : [email protected] Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
