cyrus-imapd-sphinx2.patch

   1 From a5fce9f3b5bddb166e9be71d9a0120a012d632b7 Mon Sep 17 00:00:00 2001
   2 From: Jakob Gahde <j5lx@fmail.co.uk>
   3 Date: Tue, 10 Sep 2019 16:51:32 +0200
   4 Subject: [PATCH] Add compatibility for Sphinx 2 (fixes #2732)
   5
   6 This allows the documentation to be generated using version 2 of Sphinx.
   7 Nearly all of the changes are directly based on changes in upstream Sphinx,
   8 however they have been adapted to also keep compatibility with version 1.3.2
   9 (which is the minimum version required by the current configuration).
  10 ---
  11  docsrc/conf.py                              |  6 +++---
  12  docsrc/exts/sphinxlocal/builders/manpage.py | 19 ++++++++++++++-----
  13  docsrc/exts/sphinxlocal/roles/cyrusman.py   | 11 ++++++++++-
  14  docsrc/exts/sphinxlocal/writers/manpage.py  | 11 ++++++++---
  15  4 files changed, 35 insertions(+), 12 deletions(-)
  16
  17 diff --git a/docsrc/conf.py b/docsrc/conf.py
  18 index c241cff77..ecb83768e 100644
  19 --- a/docsrc/conf.py
  20 +++ b/docsrc/conf.py
  21 @@ -301,7 +301,7 @@
  22  for tuple in pathset:
  23      os.chdir(tuple[0])
  24      for rstfile in glob.glob("*.rst"):
  25 -        author = [("The Cyrus Team")]
  26 +        authors = [("The Cyrus Team")]
  27          orphan = 'False';
  28          with io.open(rstfile,'r',encoding="utf8") as f:
  29              for line in f:
  30 @@ -309,14 +309,14 @@
  31                      orphan = 'True';
  32                      break;
  33                  if line.startswith('.. author: '):
  34 -                    author.append(line[11: len(line.strip())])
  35 +                    authors.append(line[11: len(line.strip())])
  36              f.close()
  37          if orphan == 'False':
  38              man_pages.append(
  39                  (os.path.splitext(os.path.join(tuple[0],rstfile))[0],
  40                  os.path.splitext(rstfile)[0],
  41                  u'Cyrus IMAP documentation',
  42 -                author,
  43 +                authors,
  44                  tuple[1])
  45                  )
  46
  47 diff --git a/docsrc/exts/sphinxlocal/builders/manpage.py b/docsrc/exts/sphinxlocal/builders/manpage.py
  48 index a6281f799..856530b62 100644
  49 --- a/docsrc/exts/sphinxlocal/builders/manpage.py
  50 +++ b/docsrc/exts/sphinxlocal/builders/manpage.py
  51 @@ -32,6 +32,12 @@
  52  # Translater in it.
  53  from sphinxlocal.writers.manpage import CyrusManualPageWriter
  54
  55 +try:
  56 +    from sphinx.util import logging
  57 +    logger = logging.getLogger(__name__)
  58 +except:
  59 +    logger = None
  60 +
  61  class CyrusManualPageBuilder(ManualPageBuilder):
  62      """
  63      Builds groff output in manual page format.
  64 @@ -44,8 +50,11 @@ class CyrusManualPageBuilder(ManualPageBuilder):
  65      #settings_defaults = {}
  66
  67      def init(self):
  68 +        global logger
  69 +        if logger is None:
  70 +            logger = self
  71          if not self.config.man_pages:
  72 -            self.warn('no "man_pages" config value found; no manual pages '
  73 +            logger.warn('no "man_pages" config value found; no manual pages '
  74                        'will be written')
  75
  76      def write(self, *ignored):
  77 @@ -56,7 +65,7 @@ def write(self, *ignored):
  78              components=(docwriter,),
  79              read_config_files=True).get_default_values()
  80
  81 -        self.info(bold('writing... '), nonl=True)
  82 +        logger.info(bold('writing... '), nonl=True)
  83
  84          for info in self.config.man_pages:
  85              docname, name, description, authors, section = info
  86 @@ -67,7 +76,7 @@ def write(self, *ignored):
  87                      authors = []
  88
  89              targetname = '%s.%s' % (name, section)
  90 -            self.info(darkgreen(targetname) + ' { ', nonl=True)
  91 +            logger.info(darkgreen(targetname) + ' { ', nonl=True)
  92              destination = FileOutput(
  93                  destination_path=path.join(self.outdir, targetname),
  94                  encoding='utf-8')
  95 @@ -76,7 +85,7 @@ def write(self, *ignored):
  96              docnames = set()
  97              largetree = inline_all_toctrees(self, docnames, docname, tree,
  98                                              darkgreen, [docname])
  99 -            self.info('} ', nonl=True)
 100 +            logger.info('} ', nonl=True)
 101              self.env.resolve_references(largetree, docname, self)
 102              # remove pending_xref nodes
 103              for pendingnode in largetree.traverse(addnodes.pending_xref):
 104 @@ -89,7 +98,7 @@ def write(self, *ignored):
 105              largetree.settings.section = section
 106
 107              docwriter.write(largetree, destination)
 108 -        self.info()
 109 +        logger.info('')
 110
 111  def setup(app):
 112      app.add_builder(CyrusManualPageBuilder)
 113 diff --git a/docsrc/exts/sphinxlocal/roles/cyrusman.py b/docsrc/exts/sphinxlocal/roles/cyrusman.py
 114 index 5d7eb6c65..6f2e94a8e 100644
 115 --- a/docsrc/exts/sphinxlocal/roles/cyrusman.py
 116 +++ b/docsrc/exts/sphinxlocal/roles/cyrusman.py
 117 @@ -17,8 +17,17 @@
 118  from string import Template
 119  import re
 120
 121 +try:
 122 +    from sphinx.util import logging
 123 +    logger = logging.getLogger(__name__)
 124 +except:
 125 +    logger = None
 126 +
 127  def setup(app):
 128 -    app.info('Initializing cyrusman plugin')
 129 +    global logger
 130 +    if logger is None:
 131 +        logger = app
 132 +    logger.info('Initializing cyrusman plugin')
 133      app.add_crossref_type('cyrusman', 'cyrusman', '%s', nodes.generated)
 134      return
 135
 136 diff --git a/docsrc/exts/sphinxlocal/writers/manpage.py b/docsrc/exts/sphinxlocal/writers/manpage.py
 137 index 13864e0d9..c5dfdfbeb 100644
 138 --- a/docsrc/exts/sphinxlocal/writers/manpage.py
 139 +++ b/docsrc/exts/sphinxlocal/writers/manpage.py
 140 @@ -12,13 +12,17 @@
 141      :license: BSD, see LICENSE for details.
 142  """
 143
 144 +import docutils
 145  from docutils import nodes
 146  from sphinx.writers.manpage import (
 147 -    MACRO_DEF,
 148      ManualPageWriter,
 149      ManualPageTranslator as BaseTranslator
 150  )
 151
 152 +docutils_version_info = tuple(map(int, docutils.__version__.split('.')))
 153 +if docutils_version_info < (0, 11):
 154 +  from sphinx.writers.manpage import MACRO_DEF
 155 +
 156
 157  from sphinx import addnodes
 158  from sphinx.locale import admonitionlabels, _
 159 @@ -73,8 +77,9 @@ def __init__(self, builder, *args, **kwds):
 160          self._docinfo['version'] = builder.config.version
 161          self._docinfo['manual_group'] = builder.config.project
 162
 163 -        # since self.append_header() is never called, need to do this here
 164 -        self.body.append(MACRO_DEF)
 165 +        # In docutils < 0.11 self.append_header() was never called
 166 +        if docutils_version_info < (0, 11):
 167 +          self.body.append(MACRO_DEF)
 168
 169          # overwritten -- don't wrap literal_block with font calls
 170          self.defs['literal_block'] = ('.sp\n.nf\n', '\n.fi\n')