Need to migrate config to yaml by Sept

[AlexanderPico]

https://blog.readthedocs.com/migrate-configuration-v2/

[bdemchak]

I just morphed the py4cytoscape .readthedocs.yaml file ... it existed, specified version:2, but contained a deprecated python.version command. Here's the file that readthedocs likes for py4cytoscape 1.8, which is about to be released:

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

# Required
version: 2

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

# Optionally set the version of Python and requirements required to build your docs
python:
   install:
   - requirements: doc/requirements.txt

build:
  os: "ubuntu-20.04"
  tools:
    python: "3.8"

[khanspers]

I added the yaml config file and it seems to have worked (successful build in ReadTheDocs interface). Below is what's in the file. I kept the ubuntu and python versions the same as what was suggested in the blogpost, which is different than what Barry used:

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

# Required
version: 2

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

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

# We recommend specifying your dependencies to enable reproducible builds:
# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
  install:
  - requirements: docs/requirements.txt

[khanspers]

@bdemchak : Was there a reason you changed the ubuntu and python versions from what was suggested in the blog post? Im wondering if I should keep the defaults (and consider this issue done), or if it needs to be updated further.

[bdemchak]

@khanspers Good eye ... For the ubuntu version, I don't think it matters. Both 20.04 and 22.04 are LTS and are suitable. For the python version, py4cytoscape advertises compatibility with python 3.8, so the ReadTheDocs parsing should catch any post-3.8 features I could be using. Certainly, though, my release process should also have caught this, too. So, using 3.11 should be defensible, too.

The install.requirements is necessary so that ReadTheDocs loads the dependent modules before trying to parse py4cytoscape. If I don't have this, my python will generate errors during the document compilation process.

Sensible?

[khanspers]

Thanks @bdemchak. So for the cytoscape manual, we could just not specify a Python version then? I thought it was required for the manual building process at ReadTheDocs.

[bdemchak]

@khanspers ... I don't know what ReadTheDocs assumes if the python version isn't specified, but your thought is reasonable. The main use of Python for the Cytoscape manual is in reading the conf.py file, which is 100% not controversial Python. I suspect that any Python would do, and your 3.11 idea seems fine. If there's ever a failure, it won't be subtle ... the build would fail early and the log would be obvious. With conf.py being your only real Python, it's more likely that I'd win the Miss America contest than your build would fail because of the Python setting.

While you're at it ... maybe a good idea to update the copyright year specified in conf.py??

[khanspers]

OK, copyright year has been updated in conf.py and index. The manual seems to be building without problem so Im going to close this.