| 108 | # discussion on how the signature of this class should be used |
| 109 | |
| 110 | def __init__( |
| 111 | self, |
| 112 | /, # to allow 'self' as an extras |
| 113 | buildername: str = 'html', |
| 114 | srcdir: Path | None = None, |
| 115 | builddir: Path | None = None, # extra constructor argument |
| 116 | freshenv: bool = False, # argument is not in the same order as in the superclass |
| 117 | confoverrides: dict[str, Any] | None = None, |
| 118 | status: StringIO | None = None, |
| 119 | warning: StringIO | None = None, |
| 120 | tags: Sequence[str] = (), |
| 121 | docutils_conf: str | None = None, # extra constructor argument |
| 122 | parallel: int = 0, |
| 123 | # additional arguments at the end to keep the signature |
| 124 | verbosity: int = 0, # argument is not in the same order as in the superclass |
| 125 | warningiserror: bool = False, # argument is not in the same order as in the superclass |
| 126 | pdb: bool = False, |
| 127 | exception_on_warning: bool = False, |
| 128 | # unknown keyword arguments |
| 129 | **extras: Any, |
| 130 | ) -> None: |
| 131 | self._builder_name = buildername |
| 132 | |
| 133 | assert srcdir is not None |
| 134 | |
| 135 | if verbosity == -1: |
| 136 | quiet = True |
| 137 | verbosity = 0 |
| 138 | else: |
| 139 | quiet = False |
| 140 | |
| 141 | if status is None: |
| 142 | # ensure that :attr:`status` is a StringIO and not sys.stdout |
| 143 | # but allow the stream to be /dev/null by passing verbosity=-1 |
| 144 | status = None if quiet else StringIO() |
| 145 | elif not isinstance(status, StringIO): |
| 146 | err = f"'status' must be an io.StringIO object, got: {type(status)}" |
| 147 | raise TypeError(err) |
| 148 | |
| 149 | if warning is None: |
| 150 | # ensure that :attr:`warning` is a StringIO and not sys.stderr |
| 151 | # but allow the stream to be /dev/null by passing verbosity=-1 |
| 152 | warning = None if quiet else StringIO() |
| 153 | elif not isinstance(warning, StringIO): |
| 154 | err = f"'warning' must be an io.StringIO object, got: {type(warning)}" |
| 155 | raise TypeError(err) |
| 156 | |
| 157 | self.docutils_conf_path = srcdir / 'docutils.conf' |
| 158 | if docutils_conf is not None: |
| 159 | self.docutils_conf_path.write_text(docutils_conf, encoding='utf8') |
| 160 | |
| 161 | if builddir is None: |
| 162 | builddir = srcdir / '_build' |
| 163 | |
| 164 | confdir = srcdir |
| 165 | outdir = builddir.joinpath(buildername) |
| 166 | outdir.mkdir(parents=True, exist_ok=True) |
| 167 | doctreedir = builddir.joinpath('doctrees') |