kicad-developers team mailing list archive

[Miguel Angel Ajo Pelayo <miguelangel@xxxxxxx>]

Something like this could make sense too, can be good to explore.

http://www.enricozini.org/2007/tips/swig-doxygen-docstring/

And then we get:

1) Highly documented API (on auto completion the api description from
doxygen might show up)
2) We can extract the pydoc (or do doxygen again) from our final .py
file (that has all the interface to our classes).

2012/8/8 Miguel Angel Ajo Pelayo <miguelangel@xxxxxxx>:
> 2012/8/8 Dick Hollenbeck <dick@xxxxxxxxxxx>:
>> On 08/08/2012 03:06 PM, Miguel Angel Ajo Pelayo wrote:
>>> 2012/8/8 Dick Hollenbeck <dick@xxxxxxxxxxx>:
>>>> On 08/08/2012 04:03 AM, Miguel Angel Ajo Pelayo wrote:
>>>>> After that, in the scripting console type:
>>>>>
>>>>> import pcbnew
>>>>>
>>>>> pcbnew.XXXXXX and the functions/classes that are swigged should come up there.
>>>>>
>>>>> Soon we must start documenting everything about scripting.
>>>> Its wonderful that you said that.
>>>> Then the question becomes where and how.
>>>>
>>> It's a good question,
>>>
>>>    My personal preference (if I write) would be to do it in the new
>>> web, as it's quite easy to add screenshots, colored code snippets, and
>>> keep an structured documentation that could be easily
>>> search-engine-crawled and maintained.
>>
>> That would be very nice.
>
> Yes, for some how-tos and tutorials it could be good, but probably not
> to expose the API.
>
>>
>>>
>>>    Anyway, for coherence with our other documents, that could end into
>>> a .odt/pdf later, when we have something we feel satisfied with.
>>>
>>>    What I'm not sure is how to structure the scripting documentation,
>>> I'm not specially good at this, but it's something important.
>>
>> The idea that came to be initially was to consider something like doxygen to do it, but
>> this is not something a user will typically see, at least not normally.
>>
>> Then you come to the realization that folks are both users and developers of scripts.
>> Some folks are in either or both categories.  Scripting developers need access to API
>> documentation.
>>
>> One could create a special doxygen configuration file which selects only a subset of code
>> or APIs which need to be documented specially for scripting developers.  Say such as the
>> swig sources.
>
> I think it can be a very good idea for a general scripting-API
> reference, but not sure how to
> do k with the python - extended parts,  for example:
>      http://bazaar.launchpad.net/~kicad-testing-committers/kicad/testing/view/head:/pcbnew/scripting/board.i
>
> May be we should pass all those extensions to C++ directly.
>
>>
>> These *.html outputs could then be "published" to the website using a script which invokes
>> scp or ftp (minus the password obviously).
>
> Yes, we could do it as it's done right now for the other doxygen
> references, It does bzr pull, runs doxygen,
> and then rsyncs all the doxygen output to the webserver directory.
>
>
>> This keeps the source and scripting API docs unified and in the same place.
>
> I think that we might keep an API reference and a friendly web with
> examples and explanations about how to write
> scripts, It's a mixed approach, may be it's cleaner to do it all via
> doxygen, but I feel it'd take more time to get into
> something I'd like.
>
>>
>> Then you get into the python scripts themselves.  Although currently trivially small, what
>> happens when you have scores of scripts, coming from scores of people, and nothing to
>> gather up all the information on them and their operation?  This invites consideration on
>> blending in a pydocs type of output also, and you ask each contributor to put that into
>> their script explicitly intended for extraction and subsequent publishing on the website.
>>
>> This is just Py in the sky.
>
> Hehe, about user-written scripts, some will be interesting for
> integration and some won't but
> it's something to think about, pydoc style can make sense, as it's the standard.
>
>
>>
>> Dick
>>
>>
>
>
>
> --
>
> Miguel Angel Ajo Pelayo
> http://www.nbee.es
> +34 636 52 25 69
> skype: ajoajoajo



-- 

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