How to handle linked pdf (or other) documents

[techauthoruk]

I'm not sure this is possible (!), but when I generate my Sphinx content, I often have links to other documents (pdf mainly). In the HTML output, this is fine - the pdf files are in the _static directory, and all the links work fine.

However...when I create a pdf version (rinohtype or LaTeX - same thing applies), the links to the pdf document don't work because its looking for a directory that doesn't exist. How can this be worked around?

I can manually edit the rinohtype output in Acrobat and embed the linked pdfs, but is there an easier and more graceful way of doing this? Its ok to edit in Acrobat with a small document. but it becomes very problematic on multi-page Sphinx source with many linked pdf files.

Is there a way around this? Open to suggestions!

[brechtm]

There is no support for embedding files in the generated PDF. At least not yet, but it's not on the planning either.

You can link to files on a website, but that might not be appropriate for all use cases. And that is unfortunately not straightforward to configure. I happen to have run into this requirement recently: linking to a sample PDF document from the showcase section of the rinohtype manual. This works because in this case it's possible to predict the URL of where this sample PDF will be hosted. The following may be of limited use to you, but practically I implemented this by means of the extlinks directive. This is the relevant code:

• extlinks setup in conf.py
• example use of the showcase role in showcase.rst
• because the file isn't being referenced in a traditional manner, I need to copy the sample PDF to the HTML build directory myself

The download role would be a good candidate for representing files to be embedded in a PDF. I haven't looked into whether that's even possible, and I'm not a fan of how the HTML backend implements support for this role.

[marklees-seab]

@brechtm

Interesting stuff! I'm not sure if I can make this work, and the https://github.com/brechtm/rinohtype/issues/sphinx-doc/sphinx/issues/823 link comes up with a 404 error.

I think I may just use links to the documents on the internet, but of course then if the link breaks, so does my document!

More thought needed...

[brechtm]

the https://github.com/brechtm/rinohtype/issues/sphinx-doc/sphinx/issues/823 link comes up with a 404 error.

Oops. I fixed that link now.

I think I may just use links to the documents on the internet, but of course then if the link breaks, so does my document!

If you need this for a commercial project, your employer can consider contracting me to develop the embedding of files in PDF. If you're interested, I would first investigate and give you an estimate of the amount of time required (and thus cost). Alternatively, I'm happy accepting a pull request that implements this.

[techauthoruk]

See my email - I will close this issue for now

[brechtm]

Reopening to eventually create a FAQ entry for this.