ENH: Add readthedocs config file

[jhlegarreta]

• ENH: Add readthedocs config file
• ENH: Add the numpydoc extension to process the docstrings

[jhlegarreta]

Building the documentation is failing since we modernized the package setup using pyproject.toml:
https://readthedocs.org/projects/tractolearn/builds/19396465/

The issue lies in the tomli package not being installed when building the documentation. It is required from:
https://github.com/scil-vital/tractolearn/blob/main/doc/conf.py#L15
so that the package metadata can be parsed:
https://github.com/scil-vital/tractolearn/blob/main/doc/conf.py#L23

Python seems to install it when executing the pyproject.toml, probably through the setuptools_scm requirement.

Now, if one installs tomli manually, and then sphinx-rtd-theme, the process fails because Sphinx seems to be unable to get the version using https://github.com/scil-vital/tractolearn/blob/main/doc/conf.py#L33, and fails with

(...)
    return _compile(pattern, flags).sub(repl, string, count)
TypeError: expected string or bytes-like object

Manually specifying a version makes the documentation build process partially succeed (the process exists successfully, but no content is added to the TOC/the index.html page only contains the welcome heading from index.rst; but that may be a separate issue).

There may be 2 solutions to the version issue (removing from importlib.metadata import version from https://github.com/scil-vital/tractolearn/blob/main/doc/conf.py#L16 in either case):

• Use from setuptools_scm import get_version and then _version = get_version(), assuming setuptools_scm is installed, and then assuming tractolearn gets installed by Sphinx prior to generating the documentation.
• Use

import tractolearn
_version = tractolearn.__version__

which also assumes that tractolearn gets installed.

In either case, it looks like in order to build the doc, we need to add to pyproject.toml a section with the documentation dependencies:

doc = [
 "sphinx",
 "sphinx-rtd-theme",
 "tomli",
]

and then add to conf.py:

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - doc

following https://docs.readthedocs.io/en/stable/config-file/v2.html#packages.

[jhlegarreta]

I found a way to get the version string. The documentation's first steps now work locally:

python -m sphinx -T -E -b html -d _build/doctrees -D language=en . ../_readthedocs/html

I did not go further/did not complete all steps that the successful readthedocs builds do. There are some warnings about the contents of index.rst. They require further investigation/probably it is best to address them separately.