[kea-dev] Stable links to devel doc

Baptiste Jonglez baptiste at bitsofnetworks.org
Fri Aug 25 17:54:07 UTC 2017


Hi Włodek,

On 25-08-17, Włodzimierz Wencel wrote:
> first of all thank you for developing that hook - I'm sure it will be
> useful.
> 
> As for dev docs we provide only for the current version at
> https://jenkins.isc.org/job/Kea_doc/doxygen it's updated every time
> after developers push changes to kea master branch and indexing should
> work there.
> 
> http://git.kea.isc.org/~tester/kea/doxygen/ is no longer maintained (and
> it actually should be removed).
> 
> We publish users guide for each version but never planned to do it with
> dev guide, the idea is that dev guide can be build from kea package if
> needed.

Thank you for your answer!

For developing I indeed use a locally-built version (see https://www.archlinux.org/packages/community/x86_64/kea-devel-docs/)
and this is perfectly fine.

The use-case I was talking about is having stable URLs to various points
of the development doc, as a reference.

> Is https://jenkins.isc.org/job/Kea_doc/doxygen really unusable for you?

Yes, for this "stable URLs" use-case, as outlined in my first email:

> > - there is no index or search function, so it is hard to find anything;

I see you have now enabled the menu, thanks, it will be easier :)

> > - I suspect that the Doxygen URLs are not stable, which means that over
> >   time all URLs pointing to this doc will go dead.

This is the main issue.  The links I use as reference look like this:

  https://jenkins.isc.org/job/Kea_doc/doxygen/d5/d8c/namespaceisc_1_1dhcp.html#aa5bfdcc4861aa3dab5328dba89362016

So, if any part of this URL (directory, HTML file name, hash of the
anchor) changes because of a doc rebuild or simply because the name of a
type or the name of a variable has changed in Kea, the link will not work
anymore.

This is why it would be better to have a stable version of the development
documentation, that is built once and then guaranteed to remain exactly
the same over time.

These stable devel docs could be provided outside of the Kea project, but
it seems more sustainable in the long term to do it within the project.

Regards,
Baptiste
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.isc.org/pipermail/kea-dev/attachments/20170825/c0b19c34/attachment.bin>


More information about the kea-dev mailing list