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
