kicad-developers team mailing list archive

[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.

>
>    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.

These *.html outputs could then be "published" to the website using a script which invokes
scp or ftp (minus the password obviously).

This keeps the source and scripting API docs unified and in the same place.

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.

Dick