kicad-developers team mailing list archive

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

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

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

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.

> Cheers,
>
> Wayne

Thank you for finally starting this thread.