kicad-developers team mailing list archive

[Nick Østergaard <oe.nick@xxxxxxxxx>]

Hi John,

Ok, thank your for your clarification. For the record, I am not opposing
the change, but would just mention it looks strange to add it to the
doxygen-docs target when we have the doxygen-python target.

Nick

2018-06-12 16:11 GMT+02:00 John Beard <john.j.beard@xxxxxxxxx>:

> Hi Nick,
>
> It's a related concept, certainly. The drawing helper stuff acts as a
> "buffer" between the Pcbnew API and the plugin writer, but this isn't
> really a design aim, it's just a side effect. It certainly does not totally
> insulate the writer from the Pcbnew API as it's a very limited subset of
> functionality. Thus the user is still vulnerable to Pcbnew internal API
> changes (and as Python is not a compiled language, they won't find out
> until it all explodes at runtime!). It's better than calling on the Pcbnew
> API directly (as there's only one place of breakage), but it's not a
> panacea, and was never really designed to be.
>
> However, these helpers also add some stuff that isn't just an API
> translation layer, it adds stuff like a transform stack and helpers for
> shapes like boxes and so on that would otherwise be repetitive in plugin
> code. All this can (and should) be transplanted onto a new "stable" Python
> interface in future.
>
> Cheers,
>
> John
>
> On Tue, Jun 12, 2018 at 2:47 PM, Nick Østergaard <oe.nick@xxxxxxxxx>
> wrote:
>
>> I am not sure if this will slightly derail this patch's topic. Sorry if
>> that is the case and tell me to back off.
>>
>> There have been multiple attempts on getting the python API in better
>> shape. Originally it was Ajo and some others with
>> https://github.com/kicad/kicad-python
>>
>> But the most recent work is on
>> https://github.com/pointhi/kicad-python
>>
>> Which is different from the initial work. I don't really know the state
>> of that work.
>>
>> I would like to see a supported API, but I guess this could be blocked
>> slightly because of the wxpython phoenix story.
>>
>>
>>
>> 2018-06-12 15:34 GMT+02:00 John Beard <john.j.beard@xxxxxxxxx>:
>>
>>> Hi Nick and Wayne,
>>>
>>> The patches as they are don't hook into the existing Python API doxygen
>>> stuff as it's not exactly the same as the Python API, it's a helper layer
>>> on top of that, and I was't sure if that would be OK.
>>>
>>> I will take a look at adding it to the existing Python doc generation if
>>> that's an acceptable way to present it.
>>>
>>> Cheers,
>>>
>>> John
>>>
>>> On Tue, Jun 12, 2018 at 2:11 PM, Nick Østergaard <oe.nick@xxxxxxxxx>
>>> wrote:
>>>
>>>> We already have doxygen generation for the python API, although people
>>>> say that it is easier to read the C++ one. It is generated with
>>>> the doxygen-python make target. See http://docs.kicad-pcb.org/
>>>> doxygen-python/
>>>>
>>>> Does the additions in 0002 add to the normal python docs?
>>>>
>>>> 2018-06-12 15:07 GMT+02:00 Wayne Stambaugh <stambaughw@xxxxxxxxx>:
>>>>
>>>>> Hey John,
>>>>>
>>>>> I like the idea of using doxygen to document the python plugins.  The
>>>>> current Doxyfile does not include .py files so that would need to
>>>>> change.  Before we do that, I would like to see a new section (maybe
>>>>> "Python Plugins") added to the documentation to separate the python
>>>>> plugin code from the c++ source documentation.  I can commit your patch
>>>>> as is and you can make the doxygen changes in a later patch or I can
>>>>> wait for you to create a new patch with all of the changes.  I'm fine
>>>>> either way.
>>>>>
>>>>> Cheers,
>>>>>
>>>>> Wayne
>>>>>
>>>>> On 6/4/2018 7:33 AM, John Beard wrote:
>>>>> > Hi,
>>>>> >
>>>>> > Here is a simple patch sequence for the Python Footprint Wizard
>>>>> helpers:
>>>>> >
>>>>> > 1) Minor spelling and formatting tidy-up
>>>>> > 2) Add docstrings for the wizard base. As this is intended to be used
>>>>> > by writers of new plugins, having the functions documented is
>>>>> probably
>>>>> > a Good Idea (TM)
>>>>> > 3) Add rounded rectangle and chamfered rectangle helpers. Useful for
>>>>> > some footprints or even board outlines.
>>>>> >
>>>>> > I used Doxygen-style docstrings, but I haven't actually done anything
>>>>> > about building actual output docs with it. Any thoughts of if that
>>>>> > should be done, and if so, where to put it?
>>>>> >
>>>>> > There shouldn't be anything here that will break existing plugins,
>>>>> the
>>>>> > only API changes are additions.
>>>>> >
>>>>> > Cheers,
>>>>> >
>>>>> > John
>>>>> >
>>>>> >
>>>>> >
>>>>> > _______________________________________________
>>>>> > 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
>>>>> >
>>>>>
>>>>> _______________________________________________
>>>>> 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
>>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> 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
>>>>
>>>>
>>>
>>
>