kicad-developers team mailing list archive

[Miguel Angel Ajo Pelayo <miguelangel@xxxxxxx>]

*
*Back to this old, but importan topic about scripting API documentation: *
**
*I found this at swig site:*
**2012/11/07* - Summer of Code
2012<http://sourceforge.net/p/swig/news/2012/11/summer-of-code-2012/>

GSoC 2012 was SWIG's third Summer of Code, and this year we
received five slots for projects rela.....

Parsing of C/C++ source

code has been improved, so that every declaration/definition can

now be commented. Translation of Doxygen tags to Javadoc and
Python docstrings has been improved and corresponding regression
tests have been implemented. The project mentor, Marko Klopcic
has some great ideas for the future GSoC. The work can be tried
out on the branch gsoc2012-doxygen.
              ....

I'm going to try that gsoc2012-doxygen branch and see how well or bad does
it work.

2012/8/22 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 begin_of_the_skype_highlighting            +34 636 52 25
> 69      end_of_the_skype_highlighting <%2B34%20636%2052%2025%2069>
> skype: ajoajoajo
>



-- 

Miguel Angel Ajo Pelayo
http://www.nbee.es
+34 636 52 25 69
skype: ajoajoajo