Allow custom run steps in .readthedocs.yml

[mcarans]

Currently to run custom steps in the readthedocs build process requires using a library readthedocs-custom-steps. it would be great if it were possible to run custom steps directly in .readthedocs.yml. This would need to be combined with direct specification of Python requirements in .readthedocs.yml as has previously been raised in #5572.

I could envisage something like the following:

.readthedocs.yml

version: 2
mkdocs: {}  # tell readthedocs to use mkdocs
python:
  version: 3.7
  install:
  - packages:
    - pydoc-markdown
    - readthedocs-custom-steps
  run:
    - pydoc-markdown --build --site-dir "$PWD/_build/html"

This would replace using readthedocs-custom-steps as follows:

.readthedocs.yml

version: 2
mkdocs: {}  # tell readthedocs to use mkdocs
python:
  version: 3.7
  install:
  - requirements: docs/.readthedocs-requirements.txt

docs/.readthedocs-requirements.txt

pydoc-markdown
readthedocs-custom-steps

pyroject.toml:

[tool.readthedocs-custom-steps]
script = """
pydoc-markdown --build --site-dir "$PWD/_build/html"
"""

[humitos]

Hi! Thanks for opening this issue. We have been considering adding custom steps/commands already but we haven't had the time to jump into this, yet. We created some design documents to discuss these ideas in #8190 and #8215. Please, provide any feedback you may have on those PRs that are the ones that we will come back to when we start working on this. Thanks!

[humitos]

Hi! In a few hours, we are deploying a new feature that will allow people to call arbitrary commands at different moments in the build process (see #9016). For example,

build:
  os: ubuntu-20.04
  jobs:
    post_install:
      - pydoc-markdown --build --site-dir "$PWD/_build/html"

I think this new config key, build.jobs, will cover this case. Take a look at the documentation at https://docs.readthedocs.io/en/latest/config-file/v2.html#build-jobs and please let me know if this is useful for you.

[humitos]

Besides, we are tracking "running arbitrary commands overriding Read the Docs ones" in #9062. So, I think we will be able to close this issue once you confirm us that the new config key build.jobs covers your case.

[mcarans]

@humitos I got it working. One issue is that I had to force install a different version of mkdocs that fixes this bug in mkdocs. The bug is that jinja2 3.1.0 breaks mkdocs and that causes the build to fail. Apparently "MkDocs version 1.2.4 was just released with only a fix for this, as well as version 1.3.0 with more new features."

Please can you upgrade the version of mkdocs that readthedocs uses to one that isn't broken. I've made a separate issue for this.

[humitos]

Hi @mcarans! Thanks a lot for giving it a try! I'm happy that it worked for you. I'm going to close this issue then, but feel free to re-open it if you consider.