kicad-developers team mailing list archive

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

2014-10-29 0:06 GMT+01:00 Wayne Stambaugh <stambaughw@xxxxxxxxxxx>:
> On 10/27/2014 5:36 PM, Nick Østergaard wrote:
>> 2014-10-27 21:41 GMT+01:00 Wayne Stambaugh <stambaughw@xxxxxxxxxxx>:
>>> On 10/27/2014 3:56 PM, Nick Østergaard wrote:
>>>> 2014-10-12 2:30 GMT+02:00 Wayne Stambaugh <stambaughw@xxxxxxxxxxx>:
>>>>> On 10/11/2014 8:02 PM, Mark Roszko wrote:
>>>>>>> The reason I would like to do this is in
>>>>>>> the not too distant future, I am going to convert all of our compiling
>>>>>>> documents and the coding policy into markdown
>>>>>>
>>>>>> Any interest in doing this via Jekyll? It's basically meant to do
>>>>>> markdown to HTML and one of the benefits is you can then get an
>>>>>> kicad.github.io domain and display a website using a git repository.
>>>>>> Github will automatically render using Jekyll on their end if setup
>>>>>> right so you can style your markdown docs but render like a full
>>>>>> website :)
>>>>>>
>>>>>
>>>>> Sorry about the confusion.  This is the documentation embedded in the
>>>>> KiCad source files that is parsed by Doxygen and html files are
>>>>> generated.  Doxygen also supports a limited subset of markdown which is
>>>>> useful for simple documentation such as build instructions.  I also
>>>>> created the developer's road map in markdown which gets built in to the
>>>>> full developer's documentation.  The goal is to eventually convert all
>>>>> of the plain text build instructions and any other relevant plain text
>>>>> documentation into markdown and include so we have single source for all
>>>>> of the developer's documentation.
>>>>
>>>> As mentioned in some earlier mail:
>>>> I was allowed by Ajo to play around on the Jenkins build server [1] to
>>>> add automatic building of the doxygen documatation for the purpose of
>>>> having it online and always up to date. I have dumped the links to
>>>> theese three documentaions, the doxygen-docs, dev-docs and
>>>> doxygen-python make targets on [2] under the "Developer documentation"
>>>> section. That is probably not the best place to put them, but none the
>>>> less where they are linked right now. I talked with Ajo about copying
>>>> them to somewhere on dev.kicad-pcb.org to get a shorter and easier to
>>>> remember URL. I am not sure of the best way to handle this.
>>>
>>> Nick,
>>>
>>> You didn't need to build dev-docs separately.  They are included in the
>>> doxygen-docs build.  I just added dev-docs so I didn't have to build the
>>> entire source documentation when I'm editing the developer policy
>>> documents.  Although for some reason, I don't see the "Stable Release
>>> Policy" in the main developer documentation.  I only see the road map.
>>> I'm not sure what happened there.  I have to go back and take a look at
>>> it.  Including the markdown files as separate sections isn't as clean as
>>> using the source documentation format.
>>
>> Aha, that makes more sense. I just built dev-docs because that was the
>> only thing contained the "Stable Release Policy". So I can remove that
>> target when that issue is fixed then. I did not notice that the road
>> map was included in the doxygen-docs target -- I see that now.
>
> I just commit the change to fix this so you can remove the dev-docs
> build.  The doxygen-docs build will contain the "Stable Release Policy".

Thank you. I have now removed that target from the build server and
the links pointing to that doxygen result, only linking the
doxygen-docs and doxygen-python.

>>
>>>>
>>>> This is at least a start. But when you say "KiCad for developers"
>>>> section, what do you specifically refer to? Is it [3]?
>>>
>>> This [3] seems like a logical place to put it.  I'm fine with it there.
>>>  I was thinking about adding a link to the main page to the right of the
>>> Pcbnew image in the section titled "KiCad for Developers".
>>
>> I will add it in the right hand menu. I am still not sure what we
>> should do about the confluence DEV space [3]. I think it is somewhat
>> outdated at the moment, but it also contains valuable information.
>
> Leave it there for now.  We can take a look at it when we get closer to
> release time and figure where things should go.

OK

> Thanks,
>
> Wayne
>
>>
>>>>
>>>> I would like to help with the task of integrating it.
>>>
>>> Thank you for taking care of this.
>>>
>>> Cheers,
>>>
>>> Wayne
>>>
>>>>
>>>> Regards
>>>> Nick Østergaard
>>>>
>>>> [1] http://ci.kicad-pcb.org/
>>>> [2] http://www.kicad-pcb.org/display/KICAD/KiCad+Documentation
>>>> [3] http://www.kicad-pcb.org/display/DEV/KiCad+Development
>>>>
>>