kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

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

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