I have a C++ project that I'm documenting with Sphinx. To keep the source directory clean, it uses an out-of-source build. I have a tutorial program that gets built as part of the project and generates an image in the build directory, not the project source directory. How can I reference the image in documentation files in the source directory when I have no control over the relative location of the source and build directories of the project?
I've tried using an rst_epilog in conf.py like so:
rst_epilog = """
.. |builddir| replace:: %s
""" % project_build_dir
and then refer to the image like so:
.. figure:: |builddir|/generated.png
but end up with errors like "WARNING: image file not readable: |builddir|/generated.png".
It looks like this is answered in the negative by this question: reStructured Text (Sphinx) : substitution in a file name? . Substitutions cannot be used in image directives to modify the filename and no alternative was offered other than to write a new extension or manually generate an image substitution for every image.
Related
I am using Sphinx Documentation tool alongwith LaTeX to generate pdf files.
While trying to include images in the pdf file, I am coming up with the following error during compile:
LaTeX Warning: File `{img_file}.jpg' not found on input line 920.
! Package pdftex.def Error: File `"""{img_file}".jpg' not found: using dra
ft setting.
See the pdftex.def package documentation for explanation.
Type H <return> for immediate help.
...
l.920 ...phinxincludegraphics{{img_file}.jpg}
}
?
These are some key environment variables:
A. In my conf.py, I have defined absolute path as: sys.path.insert(0, os.path.abspath('..'))
B. This is the directory tree:
docs/ # (Sphinx) Documentation folder
_build/
_static/
css/
images/
abc.jpg
img_file.jpg <= This image file is in the root ("_static") directory
_templates/
conf.py
index.rst
modules/ <= Folder containing my source (.rst) files
execute/
file_with_image.rst <= I am trying to put the image in this source file
some_other_file.rst
C. For including the image I am using the following.
.. image:: /_static/img_file.*
D. I have included graphix in conf.py preamble.
Why am I getting this error? What is the source of so many """ quotes in the error message?
Edit
On opening the *.tex file in Tex editor, this is what the code fragment from the image insertion section shows:
\subsection{Add Image}
\label{\detokenize{modules/aud_execution/add_image_with_image_directive:add-image}}\label{\detokenize{modules/aud_execution/add_image_with_image_directive::doc}}
\sphinxstylestrong{Adding an image}
Example of image usage using “image” directive:
\noindent{\hspace*{\fill}\sphinxincludegraphics{{img_file}.jpg}} % ***
Using the Quick Build, the editor throws error as under:
! Package pdftex.def Error: File `"""{img_file}".jpg' not
found: ...
However, when the curly brackets from the image file name, {{img_file}.jpg} are removed and changed it to (line marked ***):
\noindent{\hspace*{\fill}\sphinxincludegraphics{img_file.jpg}} % ***
the document successfully compiles and the image can be seen in the pdf file.
If the .tex file is saved, the pdf file in the _build/latex/ folder shows the image.
So why are the extra brackets being inserted during make latexpdf from the terminal?
Don't place your images under _static. It is special-purpose folder, not for images. E.g. create modules/execute/img/, move image there, and .. image:: img/my-image.png.
In my Sphinx documentation project, I am using images like this:
.. image:: /_static/carousel_filling.png
:width: 300px
:height: 450px
:scale: 100 %
:alt: Image here
:align: right
In the Sphinx HTML docs generated, the images are perfectly displayed in the html pages. However, when I generate pdf documents using make latexpdf, I am coming up with the following error:
'LaTeX Warning: File `{carousel_filling}.png' not found on input line ...'
I tried to find documentation related to outputting images however I came up only with this:
Excertps from:
latex_additional_files A list of file names, relative to the
configuration directory, to copy to the build directory when building
LaTeX output. This is useful to copy files that Sphinx doesn’t copy
automatically, e.g. if they are referenced in custom LaTeX added in
latex_elements. Image files that are referenced in source files (e.g.
via .. image::) are copied automatically.
So as per this, the image files should get automatically added to the output pdf file. But this is not happening. In the pdf file where the image should be there only a blank rectangle can be seen.
Interestingly, I can see that the image file has been copied to the folder _build/latex, so it means that pdflatex is able to access the image file!!
Question
How do I correctly output the images included in my Sphinx documentation in generated pdf file?
Edit 1:
In the terminal I can see the following warning:
LaTeX Warning: File `{carousel_filling}.png' not found on input line 931.
! Package pdftex.def Error: File `"""{carousel_filling}".png' not found: using dra
ft setting.
See the pdftex.def package documentation for explanation.
Type H <return> for immediate help.
...
l.931 ...t=450\sphinxpxdimen]{{carousel_filling}.png}
?
[21]
Edit 2:
In place of the image (where the rectangle outline has been output in pdf file) I can see this:
"""{carousel_filling}".png
Don't place your images under _static. It is a special-purpose folder, not for images. E.g. create img/ at the level of your rst files, move image there, and .. image:: img/my-image.png.
I am using the moderncv class to create a CV in Rmarkdown. In order to make the cv reproducible out of the box I have included the .cls and .sty files in the root directory. However, in an effort to keep the root directory uncluttered I would prefer to keep all the moderncv related files in a subdirectory (assets/tex/). I am able to access the .cls file using a relative path in the yaml front matter, but I am not able to access the .sty files unless they are in the root directory.
Searching previous questions on stackoverflow I learned the following: (1) keeping .cls and .sty files in nested directories is not recommended. I understand this and would like to do it anyway so that other people can fork my project and be able to knit the cv without having to deal with finding their texmk folder. (2) the solution to my problem seems to involve setting the TEXINPUTS using a Makefile (see this thread and another thread)
I am not very good with Makefiles, but I have managed to get one working that will knit my .Rmd file to pdf without problems, so long as the .sty files are still in root. This is what it looks like currently:
PDF_FILE=my_cv.pdf
all : $(PDF_FILE)
echo All files are now up to date
clean :
rm -f $(PDF_FILE)
%.pdf : %.Rmd
Rscript -e 'rmarkdown::render("$<")'
My understanding is that I can set the TEXINPUTS using:
export TEXINPUTS=".:./assets/tex:"
Where "assets/tex" represents the subdirectory where the .sty files are located. I do not know how to incorporate the above code into my makefile so that the .sty files are recognized in the subdirectories and my .Rmd is knit to PDF. In its current state, I get the following error if I remove the .sty files from root and put then in the aforementioned subdirectory:
! LaTeX Error: Command \fax already defined.
Or name \end... illegal, see p.192 of the manual.
which I assume is occurring because the moderncv class needs---and cannot locate---the relevant .sty files.
You could try to define the environment variable in the make rule:
%.pdf : %.Rmd
export TEXINPUTS=".:./assets/tex:"
Rscript -e 'rmarkdown::render("$<")'
Or you could set the environment variable in a set-up chunk in your Rmd file:
```{r setup, include = FALSE}
Sys.setenv(TEXINPUTS=".:./assets/tex:")
```
Note: Not tested due to lack of minimal example.
I am trying to write documentation and want and have multiply files used by multiple toc trees. Previously I used an empty file with .. include:: <isonum.txt> however, this does not work for multiply files in a directory with sub directories. Another solution I have used was to use a relative file path to the index file I am linking to. However this messes up the sphinx nav tree. So my question is how to include a directory of files with RST and Sphinx?
It can't be done, unfortunately.
The toctree directive has a glob option, which you would use like so:
.. toctree::
:glob:
generated/*
But this option is not available in the include directive.
Maybe start an issue for it?
Perhaps indicate the start and end of the section where the files should go with a comment (.. START_GLOB_INCLUDE etc), and then have a build pre-process step that finds the files you want and rewrites that section of the master file.
I am writing a documentation and I would like to include links to pdf files or zip archives. How can I achieve that using rst language and sphinx ?
If I do that
here is a pdf file : `pdf <doc/mypdf.pdf>`_
It does not work because, during the compilation sphinx do not copy the contains of the doc directory (I use the makefile generated by sphinx-quickstart).
On the contrary, using the image directive :
.. image:: img/plop.png
sphinx does copy the plop.png image in build directory. How can I obtain the same behavior for pdf or zip archive ?
A solution is to use the :download: “role” (detailed in the sphinx documentation on roles).
Here is a short example assuming you have a file mypdf.pdf in a directory doc. The directory doc and your rst file must be in the same directory:
here is a pdf file :download:`pdf <doc/mypdf.pdf>`
Note that you mustn't put a blank space between :download: and the path to the file.
The image directive also works for PDF files.
.. image:: doc/mypdf.pdf