Build failed for readthedocs.org/projects/scikit-surgeryvtk

[mxochicale]

Currently docs build is broken https://readthedocs.org/projects/scikit-surgeryvtk/builds/19697611/, leading to creating requirements-docs.txt

sphinx<=5.3.0
sphinx_rtd_theme<=1.2.0
nbsphinx<=0.8.12

It seems that we are missing .readthedocs.yaml readthedocs/readthedocs.org#6324

Some useful references:

• https://docs.readthedocs.io/en/stable/tutorial/index.html#preparing-your-project-on-github

[mxochicale]

🎉 https://readthedocs.org/projects/scikit-surgeryvtk/builds/20595454/

Read the Docs build information
Build id: 20595454
Project: scikit-surgeryvtk
Version: latest
Commit: e5f77afcce63fde6c75e68a3e66af93e13099e7b
Date: 2023-05-11T07:21:29.471464Z
State: finished
Success: True

[mxochicale]

Just for the record I tried the following configuration settings:

Build failed

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: 3.8

# Optionally declare the Python requirements required to build your docs
python:
  version: 3.8
  install:
    - requirements: requirements-docs.txt

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/conf.py

Problem in your project's configuration. Invalid "build.tools.python": expected one of (2.7, 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, pypy3.7, pypy3.8, pypy3.9, miniconda3-4.7, mambaforge-4.10, 3), got 3.8

https://readthedocs.org/projects/scikit-surgeryvtk/builds/20597464/

Build completed

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Optionally declare the Python requirements required to build your docs
python:
  version: 3.8
  install:
    - requirements: requirements-docs.txt

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/conf.py

https://readthedocs.org/projects/scikit-surgeryvtk/builds/20597493/

[mxochicale]

Adding :nonindex: removes WARNINGS but got this one which don't render docs properly:

/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:7: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:15: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:23: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:31: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:42: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:50: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:56: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:62: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:70: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:78: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:86: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:94: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:100: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:109: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:118: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:129: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:137: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:145: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'
/home/docs/checkouts/readthedocs.org/user_builds/scikit-surgeryvtk/checkouts/latest/docs/module_ref.rst.rst:153: WARNING: An option to automodule is either unknown or has an invalid value: 'nonindex'

https://readthedocs.org/api/v2/build/20776307.txt

So, I leave module_ref.rst without :nonindex:

[mxochicale]

Closing this one as build succeeded, 29 warnings. > https://readthedocs.org/api/v2/build/20802644.txt
Solution:

Removed this lines as they generate sphinx *.rst and duplicate the calls of automodule.

def generate_apidocs(*args):
    """Generate API docs automatically by trawling the available modules"""

    global working_dir, module_path
    output_path = working_dir
    apidoc_command_path = 'sphinx-apidoc'
    if hasattr(sys, 'real_prefix'):  # called from a virtualenv
        apidoc_command_path = os.path.join(sys.prefix, 'bin', 'sphinx-apidoc')
        apidoc_command_path = os.path.abspath(apidoc_command_path)
    subprocess.check_call(
        [apidoc_command_path, '--force', '--separate'] +
        ['-o', output_path, module_path] +
        [os.path.join(root_dir_abs, pattern) for pattern in exclude_patterns])


def setup(app):
    # Hook to allow for automatic generation of API docs
    # before doc deployment begins.
    app.connect('builder-inited', generate_apidocs)

p.s. Thanks to David Stansby for his input.