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.
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'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.
In the RST Documentation file, after making a :ref command, I am unable to generate a link to the targetted section.
This is the edited file:
https://github.com/rahulchhabra07/pcl/blob/master/doc/tutorials/content/narf_keypoint_extraction.rst
This is the target file: https://github.com/rahulchhabra07/pcl/edit/master/doc/tutorials/content/range_image_visualization.rst
Kindly let me know, how do I make sure the link works for the label.
I think the issue is that the range image visualization file is not getting included in the project; it's not listed in index file. So when sphinx looks for the target label, it does not find it. If you don't want the target in the toc, you can include it in it's own toc and hide it:
.. toctree::
:hidden:
filename
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
We are considering using Sphinx where I work and it appears to do everything we need. However, I am having issues getting it to match the required corporate template, which requires there to be some front matter pages inserted between the title page and table of contents.
If text is text is placed above the master table of contents in the .rst file, then it is placed above the TOC in the HTML output, but it is moved to below the TOC in the pdf output. I've also tried adding a hidden toc, but that didn't work either. The content also gets placed after the non-hidden toc.
.. toctree::
:hidden:
frontmatter
.. toctree::
:maxdepth: 2
contents_of_document
I know this has to be possible since people have published books using this tool, but I can't figure out how to do it.
I've tried this with sphinx 1.4.0 and 1.4.1. Is this something I need to add a latex sty or cls file to make it work? I would prefer not to since we would like to use both the HTML and PDF outputs.
Thanks
It looks like I need to RTFM. It is in chapter 10 to of the sphinx manual:
’tableofcontents’ “tableofcontents” call, default ’\tableofcontents’. Override if you want to generate a different table of contents or put content between the title page and the TOC.
So it order to do this, you need to learn some LaTeX as you will have to manually (or programmatically) write the from matter separately from the reST documentation.