search

varnish / varnish-modules

Collection of Varnish Cache modules (vmods) by Varnish Software
Other
185 stars 86 forks source link

Move contents from docs/foo.rst into src/foo.vcc #6

Closed lkarsten closed 8 years ago

lkarsten commented 8 years ago

We have both docs/foo.rst which contain a lot of text.

During builds vmodtool.py will create a vmod_foo.man.rst file based on our vmod_foo.vcc files. These man pages are used and distributed. The old README.rst file isn't used for much, and has at times duplicated content.

We should consider moving the contents from docs/foo.rst and put them into src/foo.vcc instead.

aondio commented 8 years ago

I can do this.

lkarsten commented 8 years ago

Related notices from lintian while building debs:

W: varnish-plus: manpage-has-bad-whatis-entry usr/share/man/man3/vmod_softpurge.3.gz
W: varnish-plus: manpage-section-mismatch usr/share/man/man3/vmod_softpurge.3.gz:3 3 != VMOD
aondio commented 8 years ago

For the record, I'm doing the changes here: https://github.com/aondio/varnish-modules/tree/man_pages

aondio commented 8 years ago

Is there a way to not generate "vmod_*.man.rst"?

dridi commented 8 years ago

I don't think there is.

aondio commented 8 years ago

Here is the PR: https://github.com/varnish/varnish-modules/pull/8

lkarsten commented 8 years ago

I've moved the changes from @aondio 's .vcc files into master and commited them now. Old manual .rst files in docs/ are deleted, and the ones built by vmodtool.py have been checked in.

People should be able to find the documentation online now. I'm not overly enthusiastic to how this turned out in the end, but I think it is an improvement overall. We need to fix vmodtool.py to get this right/clean.