VIP18, change .vcc to .rst

[Dridi Boukelmoune]

On Wed, May 10, 2017 at 7:57 AM, Poul-Henning Kamp <phk at 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