← Back to team overview

kicad-developers team mailing list archive

Re: Documentation update

 

On 4/6/2015 2:16 PM, jp charras wrote:
> Le 06/04/2015 19:55, Wayne Stambaugh a écrit :
>> One other important note.  I just noticed that the legacy odt kicad-doc
>> repo on launchpad has commits up to 4/5 (yesterday).  All of the doc
>> devs need to stop using this repo or you changes could get lost.  The
>> asciidoc documentation is now the official documentation for the project
>> so please contribute you doc changes to
>> https://github.com/ciampix/kicad-doc.  At some point I will make the
>> lp:kicad-doc repo read only for historical purposes.  There really
>> should be no more commits to lp:kicad-doc
> 
> Looks like all recent commits are only related to the GUI translations,
> not the doc translations.
> 
> No decision was taken for the GUI translations, so the "legacy kicad-doc
> repo on launchpad" is the only one repo for these translations (which
> are not related to asciidoc).

I'm not sure what you mean by GUI translations.  Do you mean the
translation of document strings to other languages or images in that go
into the documentation that show translated strings?  I would think in
either case, they should be updated in the asciidoc documentation.

> 
>>
>> On 4/4/2015 11:35 AM, Nick Østergaard wrote:
>>> 2015-04-04 17:23 GMT+02:00 Wayne Stambaugh <stambaughw@xxxxxxxxx>:
>>>> Now that we are in feature freeze, I need an update on where we stand as
>>>> far as the asciidoc documentation conversion process is concerned.  I
>>>> did a git pull yesterday and now `make html` fails for a missing po
>>>> directory.  I have a few questions about the current state of the
>>>> documentation.
>>>
>>> It is because of the way Marco made it with his Makefiles. He made it
>>> such that there was only one Makefile and then a make.sh from each the
>>> docs. This is not ideal IMHO, but I hope the CMake stuff will solve
>>> that.
>>>
>>>> 1) Is all of the legacy ODT documentation converted to asciidoc?
>>>
>>> I hope someone else can answer that.
>>>
>>>> 2) Does all the English language asciidoc build in both html and
>>>>    pdf at least on Linux?
>>>
>>> Yes. See http://ci.kicad-pcb.org/job/kicad-doc-testing/
>>>
>>> Although this is not use the cmake stuff. Still waiting on that to get merged.
>>>
>>>> 3) Do all of the supported translations build?
>>>
>>> Yes, so far. See above.
>>>
>>>> 4) I didn't see any CMake configuration files yet.  Are we making any
>>>>    progress on that front?
>>>
>>> I think the latest CMake work for the docs are in
>>> https://github.com/BrianSidebotham/kicad-doc, I have not tried
>>> building it recently because there has been no announcement on that it
>>> "should work now".
>>
>> I would like to see this ready by stable release time even though it is
>> not 100% necessary.  I'll take a look at it when I get some time.
>>
>>>
>>>> 5) Does anyone know if asciidoc supports including sections?  I would
>>>>    like to see the "Managing Footprint Libraries" pulled out of both
>>>>    the CvPcb and Pcbnew documentation so they don't have to constantly
>>>>    be kept in sync.  The other reason is that the path configuration
>>>>    dialog documentation will be identical for all of the kicad apps
>>>>    so it would be nice to only write that once.  If it is possible to
>>>>    do this in asciidoc, please create a common/ folder in the repo
>>>>    for sections that are common to help reduce maintenance.
>>>
>>> This is possible, see the end of:
>>> https://raw.githubusercontent.com/ciampix/kicad-doc/master/src/asciidoc/Pcbnew/Pcbnew.adoc
>>>
>>> I guess the github interpreter does not support it... but that should
>>> not matter for us.
>>>
>>>> 5) Do we have an autobuilder set up for the documentation so that our
>>>>    package autobuilders can pull from to provide current documentation?
>>>
>>> Yes, see earlier. This still does not nessesarely depend on the cmake
>>> stuff, because as it, it builds, and then the pdf's or whatever should
>>> just be copied to the distribution package.
>>>
>>>> 6) What else am I missing?
>>>
>>> You counted 5 twice :P
>>>
>>>> Once I have a handle on this, I would like to create an "official" repo
>>>> in github.com/KiCad.  This would only be the contents of the asciidoc
>>>> folder.  I don't want new users to be confused by the markdown and rest
>>>> folders in the current repo.  I will give the appropriate folks the
>>>> necessary privileges to maintain the new repo so I will need a list of
>>>> github users that should have these privileges.  Many thanks to our doc
>>>> devs for their efforts.
>>>
>>> I think we can move it just now. I would prefer to keep the history of
>>> the current asciidoc folder. If it is not good enough to just delete
>>> the markdown and rest folders and move asciidoc to the root, we can
>>> also use git filter-branch to get a more "clean" repo of the new
>>> documentation.
>>
>> OK.  I'll wait until Marco (or someone eles) cleans out the markdown and
>> rest folders and moves the contents of the asciidoc folder into the src
>> folder.  I don't want new contributors to be confused by the three
>> separate doc types.  This should preserve the history as well.
>>
>>>
>>> I think Marco should have access at least. I would also like to have
>>> access too. I guess those others that are likely interested will call
>>> out them selves.
>>
>> As of now I have you and Marco with repo maintenance privileges.  I'll
>> make an another announcement once the "official" repo is up and running.
>>
>>>
>>>> Cheers,
>>>>
>>>> Wayne
>>>
>>> Thank you for finally starting this thread.
>>>
>>
>> _______________________________________________
>> 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
>>
> 
> 


Follow ups

References