How to implement requirements when using a project management tool like hatch

[maxschulz-COL]

What's the problem this feature will solve?

I am currently implementing the documentation for an OS project: https://github.com/mckinsey/vizro and there we use a project management tool https://github.com/pypa/hatch

Hatch is great at managing your projects development, and in its configuration (.toml) file we specify the dev dependencies (ie also the docs dependencies)

Currently, unless I overlooked something, there is no other way to pass the docs dependencies to RTD unless I add a new requirements.txt. This would be a duplication and "hard" to maintain.

Describe the solution you'd like

I would like either a hint, or a solution on how I can pass the docs dependencies.

Best solution:

• path to a hatch environment dependencies

Second best solution:

• allow to define dependencies in the .readthedocs.yml (like that at least there is no additional file created)

Alternative solutions

So far I work with the duplicate requirements.txt

Additional context

So far RTD is awesome, this is more a quality of life improvement :)

[humitos]

Hi! I don't know too much about hatch. Could you specify the commands you would usually run to build your documentation locally?

[maxschulz-COL]

Hi! I don't know too much about hatch. Could you specify the commands you would usually run to build your documentation locally?

Yes! so I would run hatch run docs:serve

Under the hood, there are two things that feed into this. I have within my config file defined my hatch docs environment:

[envs.docs]
dependencies = [
  "mkdocs",
  "mkdocs-material",
  "mkdocstrings[python]",
]

and then also a script

[envs.docs.scripts]
changelog = "scriv create"
serve = "mkdocs serve"

which together allow me the above command. Does that help or somewhat explain where the difficulty comes from. Which is essentially a shortcut for hatch run docs:mkdocs serve, ie run mkdocs serve in in the environment docs.

[humitos]

I think I understand.

OK, it seems you should be able to use mkdocs build (instead of serve) on Read the Docs, so it generates the HTML files without starting a web server. If you use mkdocs build and then move your HTML files to $READTHEDOCS_OUTPUT/html, Read the Docs will serve your files.

I'd recommend you to use the feature build.commands (see https://docs.readthedocs.io/en/latest/build-customization.html#override-the-build-process) for your use case. An example of your .readthedocs.yaml file would be like this:

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  commands:
    - pip install hatch
    - hatch run docs:build
    - mkdir --parents $READTHEDOCS_OUTPUT
    - mv output/html $READTHEDOCS_OUTPUT/html

Note that I'm using hatch run docs:build that you will need to define first. Also note that I don't know where MkDocs will output your HTML files, so you will need to adapt the mv output/html command. I'd appreciate your feedback on this and if you were able to make it work.

[maxschulz-COL]

I think I understand.

OK, it seems you should be able to use mkdocs build (instead of serve) on Read the Docs, so it generates the HTML files without starting a web server. If you use mkdocs build and then move your HTML files to $READTHEDOCS_OUTPUT/html, Read the Docs will serve your files.

I'd recommend you to use the feature build.commands (see https://docs.readthedocs.io/en/latest/build-customization.html#override-the-build-process) for your use case. An example of your .readthedocs.yaml file would be like this:

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  commands:
    - pip install hatch
    - hatch run docs:build
    - mkdir --parents $READTHEDOCS_OUTPUT
    - mv output/html $READTHEDOCS_OUTPUT/html

Note that I'm using hatch run docs:build that you will need to define first. Also note that I don't know where MkDocs will output your HTML files, so you will need to adapt the mv output/html command. I'd appreciate your feedback on this and if you were able to make it work.

Awesome, will try that. Maybe one last QQ:

• are those commands executed from the root folder of the repository?

[humitos]

are those commands executed from the root folder of the repository?

Yes.

[maxschulz-COL]

I have seen that the build process is still in beta and that e.g. the flyout is not supported. Since this is one of the more core features we would like to use, I will pause this for now.

I have noted down however that as soon as these things are supported, we would love to jump back on the opportunity :) Thanks so much for the help, I am actually sure that this is the correct solution to the problem

[humitos]

I have seen that the build process is still in beta and that e.g. the flyout is not supported. Since this is one of the more core features we would like to use, I will pause this for now.

This is old. In fact, I updated the documentation an hour ago to reflect the reality: #10708. Projects using build.commands will get the new addons (in beta as well) which includes the flyout. Read the blog post at https://blog.readthedocs.com/addons-flyout-menu-beta/

I'd appreciate if you give it a try and give us feedback on that, since we are actively working on it and we need more users testing it and reporting issues 🙏🏼

[astrojuanlu]

To see it in action @maxschulz-COL https://docs.pypi.org/ 😄 (uses MkDocs and build.commands too, see https://github.com/pypi/warehouse/blob/d12deea005f6652862ad0b9d28ca8c3d39bc7402/.readthedocs.yml#L12-L13, https://github.com/pypi/warehouse/blob/d12deea005f6652862ad0b9d28ca8c3d39bc7402/bin/rtd-docs#L14-L19)

[maxschulz-COL]

I have seen that the build process is still in beta and that e.g. the flyout is not supported. Since this is one of the more core features we would like to use, I will pause this for now.

This is old. In fact, I updated the documentation an hour ago to reflect the reality: #10708. Projects using build.commands will get the new addons (in beta as well) which includes the flyout. Read the blog post at https://blog.readthedocs.com/addons-flyout-menu-beta/

I'd appreciate if you give it a try and give us feedback on that, since we are actively working on it and we need more users testing it and reporting issues 🙏🏼

Awesome, so I implemented the custom build, and I think the documentation works correctly (see https://vizro--6.org.readthedocs.build/en/6/)

However, I cannot see the flyout there, whereas before I think I could on PRs, is there anything additional I need to do?

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  commands:
    - pip install hatch
    - cd vizro-core/ && hatch run docs:mkdocs build
    - mkdir --parents $READTHEDOCS_OUTPUT
    - mv vizro-core/site/ $READTHEDOCS_OUTPUT/html

[humitos]

However, I cannot see the flyout there, whereas before I think I could on PRs, is there anything additional I need to do?

It should just work. I think you already found a bug 😄 . I did a quick test by myself at readthedocs/test-builds#2110 and I'm not showing the flyout in my PR 😅

I will take a deeper look to see if I can find the issue and fix it.

[humitos]

🎉 I found and fixed the issue. @maxschulz-COL Now it's working on your PR preview as well 🚀

[maxschulz-COL]

@humitos Are you sure it is fixed? Unless I am missing something, the flyout does not appear: https://vizro--6.org.readthedocs.build/en/6/

[humitos]

It does to me

Maybe it's a caching issue? Try doing a hard refresh

[humitos]

You can also try adding a query attribute to the URL to force the cache https://vizro--6.org.readthedocs.build/en/6/?cache=no

[maxschulz-COL]

It does work :) Very sleep also with the pop up that it was built from a PR :)

Thanks a lot for the support, I guess we all profited from this haha!

Maybe two last QQ:

• what is the current recommended way to get PDF docs for mkdocs? I browsed a few repos and they seem quite unmaintained (last contribution around 2021)
• with the custom build process, not only do we get the flyout now, but we are also able to version the docs right?

[humitos]

what is the current recommended way to get PDF docs for mkdocs? I browsed a few repos and they seem quite unmaintained (last contribution around 2021)

See squidfunk/mkdocs-material#4315

with the custom build process, not only do we get the flyout now, but we are also able to version the docs right?

Yes, you can have multiple active versions of your documentation and they will appear in the flyout so users can switch them over.

[humitos]

I'm closing this issue since the original issue is already solved, but feel free to re-open if you consider.

[maxschulz-COL]

@humitos I am coming back to this as there is a related issue popping up. Due to us working in a monorepo, we would love to use the functionality of cancelling builds for unrelated changes: https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition

However it seems that one cannot use commands and job concurrently.

Is there a way still to cancel custom build processes even when wanting to use jobs.post_checkout?

[humitos]

@maxschulz-COL yes. You can run any command and output 183 exit code to cancel the build https://docs.readthedocs.io/en/stable/builds.html#cancelling-builds