relative link from sphinx doc to GitHub repo

[Jan Valošek]

I would like to create symbolic link inside sphinx doc (inside https://github.com/my_repo/docs/documentation.rst file) pointing to file in same GitHub repo (e.g. https://github.com/my_repo/some_file.txt). Something like this:

`Some_file <https://github.com/my_repo/some_file.txt>`_

However, example above is absolute link. I would like to create relative link; something like this:

`Some_file <../some_file.txt>`_

Is it possible?

Thank you,

JV

[Matt from Documatt]

Hello Jan,

you can use relative URI reference like `Some_file <../some_file.txt>`_. Important is only to keep in mind that it is not relative to the RST source file (docs/documentation.rst), but to the public URL where RST source will be published.

For example, if docs/tutorial.rst ends up as mysite.com/docs/tutorial.html, a  reference `Some_file <../some_file.txt>`_ will point to mysite.com/some_file.txt.

Matt

https://blog.documatt.com

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/51373cde-a797-4595-9436-6260e0c25d78o%40googlegroups.com.

[Jan Valošek]

Hello Matt,

thanks for quick response!

Does it mean that the file I want to create reference has to be located at public URL where RST source file will be published? However I have this file located only at GitHub.

Jan

Dne úterý 7. července 2020 9:32:55 UTC+2 Matt from Documatt napsal(a):

Hello Jan,

you can use relative URI reference like `Some_file <../some_file.txt>`_. Important is only to keep in mind that it is not relative to the RST source file (docs/documentation.rst), but to the public URL where RST source will be published.

For example, if docs/tutorial.rst ends up as mysite.com/docs/tutorial.html, a  reference `Some_file <../some_file.txt>`_ will point to mysite.com/some_file.txt.

Matt

https://blog.documatt.com

On Tue, Jul 7, 2020 at 9:15 AM Jan Valošek <valos...@seznam.cz> wrote:

I would like to create symbolic link inside sphinx doc (inside https://github.com/my_repo/docs/documentation.rst file) pointing to file in same GitHub repo (e.g. https://github.com/my_repo/some_file.txt). Something like this:

`Some_file <https://github.com/my_repo/some_file.txt>`_

However, example above is absolute link. I would like to create relative link; something like this:

`Some_file <../some_file.txt>`_

Is it possible?

Thank you,

JV

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.

To unsubscribe from this group and stop receiving emails from it, send an email to sphinx...@googlegroups.com.

[Matt from Documatt]

I don't understand the last question. But to tell it in other words:  Referred URL must be relative to docs public URL. Sphinx reference `text <url>`_ will just become <a href="url">text</a>. Sphinx use URL as is - it doesn't check if it points to an existing file, is relative, copies because it's referenced, or whatever. 

For example, if https://github.com/my_repo/docs/documentation.rst will be, after build and deploy, visible at e.g.  mywebsite.com/support/documentation.html, and https://github.com/my_repo/some_file.txt will be deployed at mywebsite.com/static/some_file.txt, a relative URL in reference inside documentation.rst will be `Some file <../static/some_file.txt>`_.

Matt

https://blog.documatt.com

To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/58ac6dd5-ac81-4448-ac20-c83d19ec2073o%40googlegroups.com.

[Jan Valošek]

I am sorry for unclear question.

For example; https://github.com/my_repo/docs/documentation.rst is, after build and deploy, visible at e.g mywebsite.com/support/documentation.html. But https://github.com/my_repo/some_file.txt is not after deploy visible at mywebsite.com/... URL . This file is still only at GitHub (https://github.com/my_repo/some_file.txt). How can I include this file to deployed public URL? (I know I could put this file physically into /https://github.com/my_repo/docs/_static folder, deploy public URL and then create relative link, but I do not want to move some_file.txt into _static folder, I would like to let this file in https://github.com/my_repo/some_file.txt).

Jan

Dne úterý 7. července 2020 12:47:09 UTC+2 Matt from Documatt napsal(a):

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/58ac6dd5-ac81-4448-ac20-c83d19ec2073o%40googlegroups.com.

[Matt from Documatt]

I see! So, I would recommend Sphinx :download: role (https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-download). 

For example, :download:`../some_file.txt` in docs/documentation.rst will copy a referred file to the output, so even if some_file.txt isn't published, it will be copied to the docs. some_file.txt will be under _downloads/ in the docs. Sphinx generate a proper link to it.

Matt

https://blog.documatt.com

To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/a3f1060d-97b9-4402-9507-9eccffaeebaco%40googlegroups.com.

[Daniel Scott]

--

You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/51373cde-a797-4595-9436-6260e0c25d78o%40googlegroups.com.