kicad-developers team mailing list archive

[Miguel Angel Ajo Pelayo <miguelangel@xxxxxxx>]

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 <dick@xxxxxxxxxxx>

> 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     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> 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