kicad-developers team mailing list archive

[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