Mailing List Archive

On Wed, May 10, 2017 at 7:57 AM, Poul-Henning Kamp <phk@phk.freebsd.dk> wrote:
> I did some research on this, and created VIP18:
>
> https://github.com/varnishcache/varnish-cache/wiki/VIP-18:-RST-specification-for-code-generation

At quick glance it seems you forgot the conclusions of our discussion
and settled for sphinx integration. I thought we agreed that the
sphinx/rst2* integration of the directives would be no-op, and a
dedicated rst2vmod python script would actually generate VMOD
boilerplate code.

The idea was to hook directly into RST, see api/ and howto/:

http://docutils.sourceforge.net/docs/index.html#api-api-reference-material-for-client-developers

We don't want to hard-require sphinx at build time if we don't build the docs.

> The origin of this proposal is that the .vcc file cannot be used as README

That would be Geoff's intent, a remnant of the Varnish 3 days I'm not
particularly interested into. I don't put the same things in a readme
and in a manual. My goal is to instead take control of vmod docs,
which is not entirely the case today with vmodtool generating RST.

> in a github project, but as far as my research, neither can a .rst file with
> a custom ".. varnish::" directive ?

Github's support is very limited (and I don't blame them for that)
probably on purpose. Try an .. include:: directive too ;)

Dridi

_______________________________________________
varnish-dev mailing list
varnish-dev@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-dev

--------

I'm putting this VIP on hold for now, for the following three reasons:

I spent a day playing with sphinx/docutils extensions, and
while it is hairy, it certainly has potential for improving the
typography of our docs, but it will not materially add to the
informative content thereof.

The idea that the same file can be used as github README and
specification file dies with githubs (wise!) decision to not support
RST extension directives.

We have a handful of ideas in the pipeline (variables, counters
etc.) which requires us to extend the specification for VMODs in
as of yet unknown ways. Until we have some idea about what information
that needs to capture and what code it needs to produce, I'd prefer
to not add another level of complexity to our process.

Poul-Henning

--
Poul-Henning Kamp | UNIX since Zilog Zeus 3.20
phk@FreeBSD.ORG | TCP/IP since RFC 956
FreeBSD committer | BSD since 4.3-tahoe
Never attribute to malice what can adequately be explained by incompetence.

_______________________________________________
varnish-dev mailing list
varnish-dev@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-dev