kicad-developers team mailing list archive

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