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
Related
I work on page drafts in my sphinx doc that I don't want to be available when I run sphinx-build.
for example I have files named _bob.md , _mistbuddy.md etc.
in my conf.py file I put:
exclude_patterns = [ '**/_*']
to ignore these file.
This works on load - files ignored :
However, if I then click on one of the topics, and ALL pages are available.
I have tried .. only:: <tag> however, a directive doesn't work on all contents in a file.
Thank you.
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.
How can I get my Sphinx RST file to include a link to the "contents.html" Python help page?
More Details
I have an RST help document (index.rst) in an offline environment. I have downloaded and successfully built the Python documentation using the command make.bat html. I then copied this documentation to C:\Temp\PyDoc.
I then updated my conf.py file to include the following Intersphinx mapping:
intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}
Then, within my index.rst file, I have something like:
Contents:
.. toctree::
:maxdepth: 1
:ref:`Python <python:contents>`
The Python link is removed from the resulting documentation with the warning message:
WARNING: toctree contains reference to nonexisting document ':ref:`Python <python:contents>`'
I have verified that the output contains the text:
loading intersphinx inventory from C:/Temp/PyDoc/objects.inv...
I have also verified that the "contents" tag exists within the Python documentation by running:
python -m sphinx.ext.intersphinx "C:/Temp/PyDoc/objects.inv" | findstr contents
Which generates output that includes the line:
contents Python Documentation contents : contents.html
Does anyone know how to reference this external documentation from my RST file?
In the configuration for intersphinx, the dict's key's value is a tuple, which consists of comma-separated values, not colon-separated.
intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}
EDIT
toctree entries need a valid target, which can be a file relative to the current file or absolute as starting from the documentation root where your conf.py resides. Also the target may be an URL. I suspect that the HTML you made is none of the above, so you need to move it to a place where Sphinx can find it.
The syntax should be for documentation, not a Python object, because the page is a table of contents. I did not try this example because I don't have the Python docs downloaded and built, so I doubt it will work.
.. toctree::
:maxdepth: 1
:doc:`Python <python:contents>`
Or you can just use the URL (or similar relative or absolute target). This works for me with a fully qualified URL.
.. toctree::
:maxdepth: 1
Python <https://docs.python.org/3/contents.html>
Finally you could try an include, but I think that is not what you really want.
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.