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.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs, but you will still be able to re-open it. Thank you for your contributions.