Introduce Readthedocs config file #586

peterzahemszky · 2021-12-16T14:43:11Z

Introduce an explicit config file for Readthedocs, .readthedocs.yaml and hence close #585.

Side effect: support for installing remoteappmanager using python setup.py install is removed. (See also #577 where it was originally introduced.)

peterzahemszky · 2021-12-16T15:08:12Z

The python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html command fails on Readthedocs with the message ModuleNotFoundError: No module named 'remoteappmanager':

Running Sphinx v1.8.6

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/checkouts/586/doc/source/conf.py", line 27, in <module>
    from remoteappmanager import __version__
ModuleNotFoundError: No module named 'remoteappmanager'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/cmd/build.py", line 303, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/application.py", line 201, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/config.py", line 203, in read
    namespace = eval_config_file(filename, tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/config.py", line 380, in eval_config_file
    raise ConfigError(msg % traceback.format_exc())
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/checkouts/586/doc/source/conf.py", line 27, in <module>
    from remoteappmanager import __version__
ModuleNotFoundError: No module named 'remoteappmanager'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/checkouts/586/doc/source/conf.py", line 27, in <module>
    from remoteappmanager import __version__
ModuleNotFoundError: No module named 'remoteappmanager'

mocking modules ['pamela', 'jupyterhub', 'jupyterhub.orm', 'jupyterhub.auth', 'jupyterhub.spawner', 'docker', 'docker.errors', 'tornadowebapi', 'tornadowebapi.authenticator', 'tornadowebapi.exceptions', 'tornadowebapi.http', 'tornadowebapi.registry', 'tornadowebapi.resource'] and types [('jupyterhub.orm', 'Proxy', (<class 'object'>,)), ('tornadowebapi.registry.orm', 'Registry', (<class 'object'>,))]

codecov-commenter · 2021-12-16T15:11:52Z

Codecov Report

Merging #586 (3b6019a) into master (3957c96) will not change coverage.
The diff coverage is n/a.

❗ Current head 3b6019a differs from pull request most recent head 003634f. Consider uploading reports for the commit 003634f to get more accurate results

@@           Coverage Diff           @@
##           master     #586   +/-   ##
=======================================
  Coverage   95.35%   95.35%           
=======================================
  Files          92       92           
  Lines        4305     4305           
  Branches      422      422           
=======================================
  Hits         4105     4105           
  Misses        140      140           
  Partials       60       60

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3957c96...003634f. Read the comment docs.

peterzahemszky · 2021-12-16T15:22:19Z

The python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html command fails on Readthedocs

I can't reproduce this locally:

(venv) ~/Repositories/simphony-remote/doc/source$ python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
Running Sphinx v1.8.6
mocking modules [] and types []
loading translations [en]... done
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
[autosummary] generating autosummary for: administration.rst, api/remoteappmanager.application.rst, api/remoteappmanager.cli.remoteappdb.__main__.rst, api/remoteappmanager.cli.remoteapprest.__main__.rst, api/remoteappmanager.command_line_config.rst, api/remoteappmanager.db.csv_db.rst, api/remoteappmanager.db.interfaces.rst, api/remoteappmanager.db.orm.rst, api/remoteappmanager.docker.async_docker_client.rst, api/remoteappmanager.docker.container.rst, ..., design.rst, developer.rst, developer/ci_instructions.rst, developer/docker.rst, index.rst, troubleshoot/database.rst, troubleshoot/docker.rst, troubleshoot/general.rst, troubleshooting.rst, utilities.rst
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 40 source files that are out of date
updating environment: 40 added, 0 changed, 0 removed
reading sources... [100%] utilities                                                                                                                         
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
/home/pzahemszky/Repositories/simphony-remote/venv/lib/python3.6/site-packages/sphinx/writers/html.py:462: FutureWarning:                                   
   The iterable returned by Node.traverse()
   will become an iterator instead of a list in Docutils > 0.16.
  target_node = image_nodes and image_nodes[0] or node.parent
writing output... [100%] utilities                                                                                                                          
generating indices... genindex py-modindex
highlighting module code... [100%] remoteappmanager.utils                                                                                                   
writing additional pages... search
copying images... [100%] ./images/base_workflow.png                                                                                                         
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

peterzahemszky · 2021-12-16T15:53:25Z

The above issue was caused by the remoteappmanager not having been installed

peterzahemszky · 2021-12-16T16:26:00Z

Finished processing dependencies for remoteappmanager==2.2.0.dev0
  Traceback (most recent call last):
    File "<string>", line 1, in <module>
    File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/checkouts/586/setup.py", line 87, in <module>
      cmdclass={'install': install}
    File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/setuptools/__init__.py", line 153, in setup
      return distutils.core.setup(**attrs)
    File "/home/docs/.asdf/installs/python/3.7.12/lib/python3.7/distutils/core.py", line 148, in setup
      dist.run_commands()
    File "/home/docs/.asdf/installs/python/3.7.12/lib/python3.7/distutils/dist.py", line 966, in run_commands
      self.run_command(cmd)
    File "/home/docs/.asdf/installs/python/3.7.12/lib/python3.7/distutils/dist.py", line 985, in run_command
      cmd_obj.run()
    File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/wheel/bdist_wheel.py", line 351, in run
      self.egg2dist(self.egginfo_dir, distinfo_dir)
    File "/home/docs/checkouts/readthedocs.org/user_builds/simphony-remote/envs/586/lib/python3.7/site-packages/wheel/bdist_wheel.py", line 461, in egg2dist
      raise ValueError(err)
  ValueError: Egg metadata expected at build/bdist.linux-x86_64/egg/remoteappmanager-2.2.0.dev0-py3.7.egg-info but not found
  ----------------------------------------
  ERROR: Failed building wheel for remoteappmanager
  Running setup.py clean for remoteappmanager
Failed to build remoteappmanager
Installing collected packages: pycparser, zipp, typing-extensions, cffi, ruamel.yaml.clib, pyrsistent, importlib-resources, importlib-metadata, greenlet, cryptography, attrs, sqlalchemy, ruamel.yaml, python-json-logger, pyopenssl, Mako, jsonschema, tornado, python-dateutil, prometheus-client, pamela, oauthlib, jupyter-telemetry, entrypoints, certipy, async-generator, alembic, pyzmq, nest-asyncio, jupyterhub, jupyter-core, tabulate, setuptools, oauthenticator, jupyter-client, escapism, click, remoteappmanager
  Attempting uninstall: setuptools
    Found existing installation: setuptools 58.2.0
    Uninstalling setuptools-58.2.0:
      Successfully uninstalled setuptools-58.2.0
    Running setup.py install for remoteappmanager: started
    Running setup.py install for remoteappmanager: finished with status 'done'
ERROR: remoteappmanager==2.2.0.dev0 did not indicate that it installed an .egg-info directory. Only setup.py projects generating .egg-info directories are supported.

The error above was resolved by reverting the change introduced in #577: we now call super().run() instead of super().do_egg_install() in class install. This resolves the build issue of remoteappmanager. However, this means that the package installation will need to happen using pip install, and python setup.py install won't be supported. This is fine as the former is the general recommendation in Python land anyway

peterzahemszky · 2021-12-16T16:30:58Z

.readthedocs.yaml

+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.7"


This choice of Python 3.7 is somewhat arbitrary, but at least it matches the previous Python version used before the explicit .readthedocs.yaml config file was used. See https://readthedocs.org/projects/simphony-remote/builds/15553588/#build-commands

peterzahemszky · 2021-12-16T17:07:37Z

Given that this set of changes is fairly simple and contained, I propose merging this PR now (and addressing potential issues in follow-up PRs).

@flongford

peterzahemszky added 3 commits December 16, 2021 14:40

Introduce Readthedocs config file

6c87948

Fix build.os value

e0b49df

Fix a typo

7427665

Install the package before building the documentation

3b6019a

Revert 7f62b58 and stop supporting installation using setuptools

003634f

peterzahemszky commented Dec 16, 2021

View reviewed changes

peterzahemszky changed the title ~~[WIP] Introduce Readthedocs config file~~ Introduce Readthedocs config file Dec 16, 2021

peterzahemszky mentioned this pull request Dec 16, 2021

Set up regular documentation build on Readthedocs #584

Closed

peterzahemszky merged commit cd66aa3 into master Dec 16, 2021

peterzahemszky deleted the 585-readthedocs-config branch December 16, 2021 17:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce Readthedocs config file #586

Introduce Readthedocs config file #586

peterzahemszky commented Dec 16, 2021 •

edited

Loading

peterzahemszky commented Dec 16, 2021

codecov-commenter commented Dec 16, 2021 •

edited

Loading

peterzahemszky commented Dec 16, 2021

peterzahemszky commented Dec 16, 2021

peterzahemszky commented Dec 16, 2021

peterzahemszky Dec 16, 2021

peterzahemszky commented Dec 16, 2021

Introduce Readthedocs config file #586

Introduce Readthedocs config file #586

Conversation

peterzahemszky commented Dec 16, 2021 • edited Loading

peterzahemszky commented Dec 16, 2021

codecov-commenter commented Dec 16, 2021 • edited Loading

Codecov Report

peterzahemszky commented Dec 16, 2021

peterzahemszky commented Dec 16, 2021

peterzahemszky commented Dec 16, 2021

peterzahemszky Dec 16, 2021

Choose a reason for hiding this comment

peterzahemszky commented Dec 16, 2021

peterzahemszky commented Dec 16, 2021 •

edited

Loading

codecov-commenter commented Dec 16, 2021 •

edited

Loading