Documentation build failing: can we enable RTD preview on PRs?

[krassowski]

The documentation test on CI passes, but the actual build on RTD fails with:

The configuration key "build.os" is required to build your documentation. Read more at https://docs.readthedocs.io/en/stable/config-file/v2.html#build-os

See build 21951693.

I would suggest that we enable documentation preview from pull requests to prevent such problems in the future (and make reviewing PRs with changes to docs easier); this will require four clicks by one of the nbdime RTD admins (I can do this if you would like to add me).

[krassowski]

With #686 merged the build is now failing later on in the process (traceback below). Adding RTD build preview on PR would really help contributors to ensure the docs are building. I would appreciate if one of the nbdime RDT maintainers (@willingc @minrk @vidartf) could chime in or enable the preview :)

Building wheels for collected packages: nbdime
  Building wheel for nbdime (pyproject.toml): started
  Building wheel for nbdime (pyproject.toml): finished with status 'error'
  error: subprocess-exited-with-error
  
  × Building wheel for nbdime (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [58 lines of output]
      running bdist_wheel
      running js
      /tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/config/setupcfg.py:293: _DeprecatedConfig: Deprecated config in `setup.cfg`
      !!
      
              ********************************************************************************
              The license_file parameter is deprecated, use license_files instead.
      
              By 2023-Oct-30, you need to update your project and remove deprecated calls
              or your builds will no longer be supported.
      
              See https://setuptools.pypa.io/en/latest/userguide/declarative_config.html for details.
              ********************************************************************************
      
      !!
        parsed = self.parsers.get(option_name, lambda x: x)(value)
      `npm` unavailable.  If you're running this command using sudo, make sure `npm` is available to sudo
      Traceback (most recent call last):
        File "/home/docs/checkouts/readthedocs.org/user_builds/nbdime/envs/latest/lib/python3.8/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/home/docs/checkouts/readthedocs.org/user_builds/nbdime/envs/latest/lib/python3.8/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
        File "/home/docs/checkouts/readthedocs.org/user_builds/nbdime/envs/latest/lib/python3.8/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 251, in build_wheel
          return _build_backend().build_wheel(wheel_directory, config_settings,
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/build_meta.py", line 434, in build_wheel
          return self._build_with_temp_dir(
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/build_meta.py", line 419, in _build_with_temp_dir
          self.run_setup()
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/build_meta.py", line 341, in run_setup
          exec(code, locals())
        File "<string>", line 173, in <module>
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/__init__.py", line 103, in setup
          return distutils.core.setup(**attrs)
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/_distutils/core.py", line 185, in setup
          return run_commands(dist)
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/_distutils/core.py", line 201, in run_commands
          dist.run_commands()
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/_distutils/dist.py", line 969, in run_commands
          self.run_command(cmd)
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/dist.py", line 989, in run_command
          super().run_command(command)
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/_distutils/dist.py", line 988, in run_command
          cmd_obj.run()
        File "/home/docs/checkouts/readthedocs.org/user_builds/nbdime/checkouts/latest/setupbase.py", line 484, in run
          [self.run_command(cmd) for cmd in cmds]
        File "/home/docs/checkouts/readthedocs.org/user_builds/nbdime/checkouts/latest/setupbase.py", line 484, in <listcomp>
          [self.run_command(cmd) for cmd in cmds]
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/_distutils/cmd.py", line 318, in run_command
          self.distribution.run_command(command)
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/dist.py", line 989, in run_command
          super().run_command(command)
        File "/tmp/pip-build-env-vi8q_ceb/overlay/lib/python3.8/site-packages/setuptools/_distutils/dist.py", line 988, in run_command
          cmd_obj.run()
        File "/home/docs/checkouts/readthedocs.org/user_builds/nbdime/checkouts/latest/setupbase.py", line 267, in run
          c.run()
        File "/home/docs/checkouts/readthedocs.org/user_builds/nbdime/checkouts/latest/setupbase.py", line 405, in run
          raise ValueError(('missing files: %s' % missing))
      ValueError: missing files: ['/home/docs/checkouts/readthedocs.org/user_builds/nbdime/checkouts/latest/nbdime/webapp/static/nbdime.js']
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for nbdime
Failed to build nbdime
ERROR: Could not build wheels for nbdime, which is required to install pyproject.toml-based projects

[vidartf]

I've enabled the previews, and added you as a maintainer on RTD @krassowski ,

[krassowski]

Thank you!

[krassowski]

In #697 it looks that the PR builds are still not triggered and webhook may need re-syncing as per https://docs.readthedocs.io/en/stable/guides/pull-requests.html#troubleshooting but this needs to be done by repo admin:

[minrk]

I resynced the webhooks before opening #698, which does appear to have gotten RTD preview renders, so I think this works now? Sorry for not noticing #697 before opening #698.

[krassowski]

Thank you @minrk!