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|
Related
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.
I am in process documenting my python library. I would like to add custom icons. I see I can add font awesome icons. However, I must not be googling very well or...
Is it possible to add custom icons to Sphinx(-rtd-theme)? If so, is there an example? I cannot find one. Thank you.
The closest thing I found was the sphinx-design package then using the avatars class with the {div} directive (Myst). e.g.:
:::{div}
<img src="images/whale_trace.png" class="sd-avatar-md sd-border-1">
:::
note: i use .md instead of .rst. Thus, I use the Myst parser. In order to copy the image over and use the right path, the conf.py file needs to be modified :
myst_enable_extensions = ["colon_fence", "html_image"]
adding html_image will all resolution of the image. See Myst documentation:
> Blockquote
HTML parsing to the rescue!
By adding "html_image" to myst_enable_extensions (in the sphinx conf.py configuration file), MySt-Parser will attempt to convert any isolated img tags (i.e. not wrapped in any other HTML) to the internal representation used in sphinx.
_
Context
I am using Sphinx to create technical documentation (not code-related). The input are several reStructuredText and SVG files. The output is created using the singlehtml builder (which is converted to PDF using weasyprint in a later step).
Problem
I would like to include a table of contents (TOC) in the final document. The default location for the TOC (sidebar) is not an option. I have to disable/hide the sidebar to generate a useful PDF.
Solutions (I have considered / tried)
toctree directive: Seems to only work with the sidebar, no matter what I try.
HTML Theming: I'm using it for styling the HTML output, but I would not know how to address the TOC issue.
Sphinx extensions: I wrote my own, but it's not very flexible and I'm still sure that others have already solved this problem.
Use latexpdf builder: Tried that and it solves the TOC problem, but it creates a few other problems and styling the document is so much easier for me using CSS.
Other tool than Sphinx: Is this a typical case of an XY problem? I would like to use reStructuredText and SVGs to generate a PDF, but I would be open to use something else than Sphinx.
Use the contents directive.
Here's the directive in its simplest form:
.. contents::
Language-dependent boilerplate text will be used for the title. The English default title text is "Contents".
An explicit title may be specified:
.. contents:: Table of Contents
As #mzjn already suspected, .. contents:: only lists the contents of the current file, but if I use .. include:: instead of .. toctree:: to include other documents, it works nevertheless. So what I'm currently using is this:
.. sectnum::
.. contents:: Table of Contents
:depth: 2
.. include:: intro.rst
.. include:: processes.rst
Using Sphinx documentation generator (with pdflatex), I am creating pdf files and have added links to some of the internal files using label and ref markups like this:
In the called file (xyz.rst)
.. _called-file-label:
In the calling file(abc.rst) I am adding a reference to the label like this:
:ref:`Get Info <called-file-label>`
With the above arrangement, I am able to generate pdf file using pdflatex. However, I find that the called file is also added to the pdf file's bookmarks section which feels somewhat clumsy.
I understand I need to add both the source files in the .. toctree:: section for the hyperlink to appear in the pdf file (I have added the called file using :hidden: directive to prevent the file from showing up in the html document's ToC tree).
My question is: What do I need to do in order that the called file (xyz.rst) does not figure in the bookmarks section of the generated pdf file?
If after .. _called-file-label: label is section:
.. _called-file-label:
Foo Bar
======
Then, the section title "Foo Bar" will always become a bookmark in PDF.
The :hidden: option of toctree is not to hide documents, but to don't show ToC on the place with toctree. I.e. it is to hide toctree, not its documents. Documents in hidden toctree will still be visible in HTML sidebars, PDF bookmarks, etc.
It looks like you need rubric directive. Rubric is like a section, but doesn't make up the table of contents.
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.