[Varnish] #1681: Use of "Manual Section" in rst docs to properly generate manpages sections

[Varnish]

#1681: Use of "Manual Section" in rst docs to properly generate manpages sections
---------------------------------+---------------------------
 Reporter:  gui                  |       Type:  documentation
   Status:  new                  |   Priority:  normal
Milestone:  Varnish 4.0 release  |  Component:  documentation
  Version:  4.0.3                |   Severity:  normal
 Keywords:                       |
---------------------------------+---------------------------
 Hi,

 The Debian project parse manpages of upstream projects to track
 errors/warning [1]. There is non declared macros by rst2man because your
 rst files in doc/sphinx/reference/ does not define header macros that
 could be used to generate properly section for manpages (also note that
 you can move your bottom defined Copyright and Author in the header with
 ":Copyright: " and :"Author: "). Example for
 doc/sphinx/reference/varnishstat.rst file:

 {{{
 [...]
 ---------------------------
 Varnish Cache statistics
 ---------------------------

 :Manual section: 1

 SYNOPSIS
 ========
 [...]
 }}}


 For information (for vsl-query and varnish-cli), i've also proposed to
 docutils project to always quote the title; when there is a space in, the
 section is wrong (set as the second word of the title) [2].

 If you agree with this, i can provide a patch for all rst that are
 generated as manpages.

 Html generated pages are also changed when adding these macros.

 Sources:
 * [1] https://lintian.debian.org/maintainer/pkg-varnish-
 devel at lists.alioth.debian.org.html#varnish
 * [2] https://sourceforge.net/p/docutils/patches/126/

-- 
Ticket URL: <https://www.varnish-cache.org/trac/ticket/1681>
Varnish <https://varnish-cache.org/>
The Varnish HTTP Accelerator