I'm generating sphinx documentation with.md files that reference images via relative paths:
I use MyST to parse the .md files into html, but it removes the ../' making all paths:
_static/figures/image.png.
The relative paths work fine before documentation generation and has to kept the same.
In the conf.py for sphinx I copy over the images as html_static_path files, and if the path is kept the same in the html, the images would show.
The MyST docs state that it copies .md images but give no configuration options for copying. The paragraphs below only reference how to parse HTML files with images. I did find another option that should treat all links as hyperlinks, but this made no change.
How do I force MyST to not change the image paths?
I think it is more of a convention question.
It is recommended to put _static in all folder levels and separate assets like images inside each of them, so that links like _static/figures/image.png resolve to just that folder level.
If you want to use a single top level _static folder for all folder levels, then your links should be written as /_static/figures/image.png, where they are resolved to the top level.
Related
I have a book with the following directory structure
book.adoc
chapters/chapter1.adoc
chapters/chapter2.adoc
chapters/chapter3.adoc
images/img1.jpg
images/img2.jpg
in book.adoc I include the chapters. The problem is that in each chapter I include images from the images directory. If I use a path relative to book.adoc then the images render when I generate the PDF of the entire book, but not when I generate a PDF of an individual chapter.
This is particularly annoying when working on a chapter and the HTML preview does not show the images.
Is there a way to specify the paths so it works in both cases? Is the only way to move the chapters up a directory?
Yes. Your documents can specify the imagesdir attribute. See the documentation.
If you specify imagesdir as a relative path, such as ./images, then you can have chapter-specific image folders that should allow your full and chapter-specific builds to work, as well as make the HTML preview work.
I have the following sphinx directory structure for my project.
/applications
/app1
Content.rst
/app2
Content.rst
/components
/component1
Content.rst
/figures
Figure1.png
/component2
Content.rst
/figures
Figure1.png
For each reuseable UI software component I have a separate directory including some screenshots of the UI in figures. Every component has some figures, which makes directories easily moveable and re-namable, by using image directives using relative paths.
Furthermore, I have applications for our end user clients. But not every component is used in every application.
Now a problem with relative and absolute paths occurred. Assume that applications/app1/Content.rst contains somewhere:
.. include:: components/component1/Content.rst
Furthermore assume that components/component1/Content.rst contains somewhere:
.. image:: figures/Figure1.png
Now the file rst file of component1 is found an included in my documents, but the images of component1 are not included in the document.
Python Sphinx prints:
WARNING: image file not readable: figures/Figure1.png
Seemingly there is an issue with relative paths here, that I couldn't solve after trying for hours. I even still wonder what is the present working directory while processing components/component1/Content.rst.
I also want to avoid absolute paths in the Content.rst of the components if possible.
Any help for my problem is highly appreciated.
Review
If I change the image line to:
.. image:: components/component1/figures/Figure1.png
The image is displayed, but now I have a serious problem if I need to move or to rename my component.
But now I have another problem: In case someone wanted to include components/component1/Content.rst in the index.rst via the toctree:: command. Then the images are looked at components/component1/components/component1/figures/Figure1.png, which is wrong again.
Within the markdown document, what is the proper syntax to go up one directory and then choose the file? It will be rendered online, so would html ../ be appropriate to put in the markdown syntax?
such as [some_description]andthen(../file_name.md)
I had to add the "and then" to get it to show up on stack....
Links work the same way in Markdown as they do in HTML. A relative path would work the same way.
[I'm a relative reference to a repository file](../blob/master/LICENSE)
which is from here: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#links
I have just recently (yesterday) started using sphinx and read the docs for my project.
Till now I am happy with the Html documentation but the pdf version includes all the articles That appear in the index within the Contents heading. And the Documents orignal content/index is simply comprised of two links.
Please help.
The documentation is at http://todx.rtfd.io and the pdf is here.
When generating the PDF, Sphinx is always adding the content that is referenced via a .. toctree:: directive exactly where the directive is placed.
In contrast, when generating HTML, Sphinx is placing the content after the file that contains the toctree.
In this aspect, PDF generation and HTML generation are simply inconsistent.
Thus, you should place all content of the index page before the table of contents.
In case you want to provide an overview of the most important sections inline, you can use a list of references. Then, you might want to hide the toctree using the hidden property, for example like this:
Contents
--------
- :ref:`quickstart`
- :ref:`userguide`
Features
--------
- Fast
- Simple
- Inituitive
- Easy to Use
- Offline
- Open Source
.. toctree::
:hidden:
quickstart
userguide
Sphinx (http://sphinx-doc.org/index.html) uses restructured text to define the content. There are directives to display images from the local file system (using relative and absolute paths).
What I'd like to be able to do is declare an image using a URL and have it displayed in-line. The only way I can see this is to specify raw HTML, which seems a little crude. Is there an alternative - perhaps another "hidden" directive or plugin to support this?
The reason I need this is that I have a lot of images. If I store them on github I'll be forcing my users to download quite a large file to sync. I do appreciate I would lose the benefit of warnings from Sphinx for missing files.
To include an image from an URL you can put in your source.rst:
.. image:: http://my.url.com/my-picture1.png
:alt: my-picture1
You may also put at the end of conf.py:
# A string of reStructuredText that will be included at the end of every source
# file that is read.
rst_epilog = """
.. |pic2| image:: http://my.url.com/my-picture2.png
:alt: my-picture2
"""
and in source.rst:
|pic2|
Finally, if you have a lot of images in the same place, you could do this: in conf.py put:
# The URL base of images
url_base = "http://my.url.com"
# A string of reStructuredText that will be included at the end of every source
# file that is read.
rst_epilog = """
.. |pic3| image::{url_base}/my-picture3.png
:alt: my-picture3
.. |pic4| image::{url_base}/my-picture4.png
:alt: my-picture4
""".format(url_base=url_base)
and in source.rst:
|pic3|
|pic4|