kicad-developers team mailing list archive

[John Beard <john.j.beard@xxxxxxxxx>]

Hi Wayne,

It is not a replacement for the existing doxygen docs, which are
unaffected by this patch.

This patch merely allows you to generate the docset if you wish, it's
not an ALL target. My intention here is to provide a way for CI
systems to generate these docs and provide an continuously updating
docset, in the same way that the doxygen is kept up-to-date.

Zeal (available on Win, Linux and Mac, and the commercial Dash for Mac
and I think other equivalents) allow the documentation to be available
offline and much more quickly searchable, as well as providing editor
integration (I know at least vim, emacs and sublime all have
integrations).

Attached is a very short video showing the current docsets, as hosted
on github. To use them right now, add this XML feed to Zeal: [1].
(Note: the -dirty suffix is due to the presence of this change on top
of master while the docset is generated!)

As for the python script, availability in pip mean it can be installed
easily with virtualenv, so you don't have to (and, with a package
manager, should not) install at a system level. It is packaged in the
AUR on Arch for python2. Again, you don't need it if you do not intend
to generate any docsets yourself. If you do not have it, the CMake
target is not created, just like the current doxygen target.

PSA: Regardless of KiCad, I would recommend Zeal to anyone solely for
the C, C++, CMake and wxWidgets references.

Cheers,

John

[1]: https://raw.githubusercontent.com/johnbeard/kicad-docset/master/feeds/master/KiCad.xml
On Wed, Nov 28, 2018 at 4:07 PM Wayne Stambaugh <stambaughw@xxxxxxxxx> wrote:
>
> Hey John,
>
> What exactly does this buy use over the regular doxygen docs?  I'm not
> familiar with Zeal.  I don't have the tools installed on my machine to
> verify this and I'm not a big fan of using pip on a system that uses a
> package manager.  Is doxytag2zealdb packages for any distros?  I would
> like a better picture of what this brings to the table and the
> availability of any dependencies before I commit it.
>
> Cheers,
>
> Wayne
>
> On 11/27/2018 12:28 PM, John Beard wrote:
> > Hi,
> >
> > This is a patch to generate docsets using our existing doxygen set-up.
> > Docset documentation makes it very easy to quickly browse the docs
> > using Zeal and similar [1], which means you can get IDE integration
> > and other nice things.
> >
> > The patch adds a "make docset" target. To actually build the docset,
> > you will need doxytag2zealdb, a Python program available with pip.
> >
> > There is a strange extraneous endif() in the existing version Cmake as
> > well, which I
> > cannot explain why it currently works at all in its current form!
> >
> > The docset can be used to construct a docset feed using the CI
> > infrastructure. Basically you need to host the TGZ somewhere and then
> > provide an XML which changes the version and the link as needed. Zeal
> > then picks up new version availability when checked.
> >
> > I have a hastily constructed feed available here [2]. This means you
> > can start using a nightly-ish docset today, but updates are not done
> > by a CI system. It should be as simple as adding this URL in Zeal [3].
> >
> > Cheers,
> >
> > John
> >
> > [1]: zealdocs.org
> > [2]: https://github.com/johnbeard/kicad-docset
> > [3]: https://raw.githubusercontent.com/johnbeard/kicad-docset/master/feeds/master/KiCad.xml
> >
> >
> > _______________________________________________
> > 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
> >
>
> _______________________________________________
> 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