How to specify a file that can be downloaded via ReadTheDocs with MkDocs

Question

Presently, i am using https://pypi.org/project/mkdocs-with-pdf/

  - with-pdf:
      cover_subtitle: PDF created with mkdocs-with-pdf
      # TODO: find a way to use $READTHEDOCS_OUTPUT and $READTHEDOCS_PROJECT
      # output_path: $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT.pdf
      output_path: builds.pdf

With the aim to build a .pdf file. This works fine, and i have confirmed through post-build jobs that this exists, as well as the build logs.

My issue is that I am unsure how to make this appear in the ReadTheDocs downloads area. Presently a PDF option appears but clicking on it simply guides me to a broken html page.

I have tried to move the PDF File to the recommended output area, as suggested by RTD page

    post_build:
      - mkdir -p $READTHEDOCS_OUTPUT/pdf/
      - mkdocs build
      - ls -lR
      - mv ./site/builds.pdf $READTHEDOCS_OUTPUT/pdf/

This has not changed my issue, but it has confirmed the location of the pdf file i want to be downloadable

Any Suggestions?

I have tried several other options, none have changed my outcome so i do not have a direct list of these. I have tried htmlzip and used parts of this branch: https://github.com/readthedocs/test-builds/tree/mkdocs-pdf

I was expecting to have an easy-to-download built pdf.

Answer 1

Read the Docs looks for the file in a pretty specific location (directory and filename). You need to change this line:

      - mv ./site/builds.pdf $READTHEDOCS_OUTPUT/pdf/

by

      - mv ./site/builds.pdf $READTHEDOCS_OUTPUT/pdf/$READTHEDOCS_PROJECT.pdf

That should work.