2

I am a relative beginner developing a Python package. At the root of the repository there are two important directories: images and docs. The former contains some png and svg files I would like to put inside a documentation, the latter is where I run sphinx-quickstart in. I cannot change that layout therefore I have to let Sphinx know to use the top-level images directory while building the docs.

According to what I found over the internet I adjusted the conf.py file to have:

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static', '../images']

And in the index.rst I have to point to the image file itself:

.. image:: ../images/scheme.svg
   :width: 500
   :alt: schematic
   :align: center

Having these two set up I run make html and I do get clean logs but the output directory is a little strange... Once the build is finished i have a docs/_build/html directory which contains _static and _images sub-directories (among many others). What I find strange is that inside docs/_build/html/_static I see all the contents of the root-level images being copied over whereas (at the same time) inside docs/_build/html/_images I only have scheme.svg. So essentially this one file is duplicated into these two subdirectories...

This does not look very clean to me... how should I adjust this setup?

Reply to the comment of bad_coder:
Below I will paste a tree with the dir structure (kept only the relevant elements):

.
├── docs
│   ├── Makefile
│   ├── _build
│   │   └── html
│   │       ├── _images
│   │       │   └── scheme.svg
│   │       ├── _static
│   │       │   ├── scheme.svg
│   ├── conf.py
│   ├── index.html
│   ├── index.rst
├── images
│   ├── scheme.svg
maciek
  • 1,807
  • 2
  • 18
  • 30
  • Can you please edit the question to include a file/directory tree [like in this answer](https://stackoverflow.com/a/60159862) instead of describing the file structure in words. It makes the question much easier to read and understand. – bad_coder Apr 06 '21 at 16:25
  • AFAIK, you cannot configure the destination, and files and directories will be copied relative to the build directory. – Steve Piercy Apr 07 '21 at 08:02
  • @bad_coder: I have adder the directory tree, updated the question. – maciek Apr 09 '21 at 23:29
  • @StevePiercy: I am fine with not having a configuration for the destination but still, something looks messed-up in this setup - I should not have the same svg file being copied into two separate places in the destination after build> – maciek Apr 09 '21 at 23:29
  • 1
    That might be an artifact of an earlier build. Do a `make clean`, then `make build`. Also you try removing , '../images' from `html_static_path = ['_static', '../images']`. – Steve Piercy Apr 10 '21 at 07:38
  • @StevePiercy: It was not an artifact - the setup I described above leads to the duplication of the .svg (I checked again after cleaning up). However, when I removed the additional dir from `html_static_path` I get a better outcome: the svg is available under `_build/html/_images` but not under `build/html/_static` anymore. What is the point of this config option then... Am I understanding it wrong? – maciek Apr 10 '21 at 12:02
  • 1
    `html_static_path` is used primarily for theme files (Jinja2) that reference static files. This method is actually now secondary to the preferred method of declaring extra CSS and JS in the `conf.py` via [html_css_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files) and [html_js_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_js_files). It is not used when Sphinx renders reST content. Sphinx will copy files that are referenced in reST directives, for example `image`, into the build directory. – Steve Piercy Apr 11 '21 at 05:37
  • OK, thanks a lot! You want to re-write this into an answer so that I can accept? – maciek Apr 11 '21 at 09:47

0 Answers0