Sphinx

[BalzaniEdoardo]

Switch to sphinx pydata theme.

Adding some notes here on the docstrings parsers:

• numpy uses the extension numpydoc for docstrings parsing; we are using another sphinx extension called napoleon. numpydoc works best in parsing, way less unexpected rendering (for example, multi-line exceptions renders fine), but it doesn't support type hinting (type hinting are dropped). This is because numpy doesn't support type hinting too (see here for a discussion: Support type annotations (PEP 484) numpy/numpydoc#196). In the future this may change and I will strongly recommend to switch to numpydoc. Napoleon has a clear bug in sphinx/ext/napoleon/docstring.py:

    def _parse_raises_section(self, section: str) -> list[str]:
        fields = self._consume_fields(parse_type=False, prefer_type=True)
        lines: list[str] = []
        for _name, _type, _desc in fields:
            m = self._name_rgx.match(_type)
            if m and m.group('name'):
                _type = m.group('name')
            elif _xref_regex.match(_type):
                pos = _type.find('`')
                _type = _type[pos + 1 : -1]
            _type = ' ' + _type if _type else ''
            _desc = self._strip_empty(_desc)
            _descs = ' ' + '\n    '.join(_desc) if any(_desc) else ''  # here they are creating a string that doesn't render as HTML
            lines.append(f':raises{_type}:{_descs}')
        if lines:
            lines.append('')
        return lines

but I don't know what to do about it. For now, I split the exception into multiple (i.e. a ValueError with few cases, is split into multiple errors of one case).