By using image directive, the images are searched either in the current directory or captured directly with an absolute path.
Is there any way to extend the search path with other directories?
Example
Environment setup
Location of the .rst file: project_path/sphinx/source/core/myrst.rst
Location of the .png file: project_path/doxygen/html/myimage.png
Current scenario
Referencing the .png file:
.. image::../../../doxygen/html/myimage.png
Desired scenario
Referencing the .png file:
.. image_or_any_other_directive::myimage.png
Is there any sphinx extension that provides this functionality?
Related
I can make asciidoc use the local directory for the stylesheet by using the full path:
:stylesheet: /this/complicated/path/my.css
But I want to make my document both self-contained and movable. Is there a way to specify that I want it to use the file my.css from the same directory where the .adoc file is located?
If you do not specify a path, the stylesheet is assumed to be in the same directory as the document:
:stylesheet: my.css
See: https://asciidoctor.org/docs/user-manual/#applying-a-theme
I am generating docs using rst/sphinx and am having a problem with images in referenced files.
The include directive works well to bring in rst files, but I am not getting the images that are themselves referenced from the included files.
My structure is like this:
/documentation
/master_doc
/source
pointer_file.rst
and this file calls file.rst:
include:: ../../doc_a/source/file.rst
/documents
/doc_a
/source
/images
picture.jpg
file.rst
includes a figure ref:
.. figure:: images/picture.jpg
When I build from doc_a directory, I get text + image. All good.
But when I build from the master_doc directory, where the include directive comes in, I get only the text and the image is missing in the build.
How can I fix this? I don't want to have to duplicate all my images in both directories, which is the only thing that seems to work at present.
***EDIT: Added detail to project structure above since suggested fix below does not yet work.
I tried all of the following in response to the suggestion in the first comment, and none of it worked:
.. figure:: /documentation/documents/doc_a/source/images/picture.jpg
and
.. figure:: /documents/doc_a/source/images/picture.jpg
and
.. figure:: /doc_a/source/images/picture.jpg
Any other ideas?
Try changing your image file path from relative to absolute.
.. figure:: /doc_a/source/images/picture.jpg
From reStructuredText Primer, Images:
When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.
I solved this problem. Thanks to Steve Piercy for asking helpful questions. I had to do 2 things:
move all images to a shared_images folder, at the same relative distance from all doc projects, and
re-organize my project folders to make them siblings.
Now my image refs are all to: ../../../shared_images/.
It works!
I'm new to sphinx and I need to pass a value from conf.py to my rst files. Is this possible from within sphinx?
My use case is the following: I want to include code snippets that are generated along with the documentation. The problem is that the files reside in a build directory, and I have no way of knowing the relative path between the source and build directory.
index.rst:
.. literalinclude:: |BUILD_DIR|/generated.txt
The conf.py is generated at compile time and contains the path to the build directory.
I am using asciidoc with asciidoctor to create documentation for a current project.
I notice there is a markup to include files in the documentation like so:
link:index.html
or
link:protocol.json[Open the JSON file]
Is it possible to include a docx file as a link so that it would open externally or be able to downloaded?
Also can I put this file in a folder inside my asciidoc directory (for the sake of organization) and still be able to properly reference it?
You write something like this:
Open this link:somefile.docx[Word file] should work.
Or this link:file:///C:/Users/xxx/docs/otherfile.docx[second file].
It works with relative path or absolute path.
You need to ensure that the path to your file will be correct for the reader of your document.
Example: if you put the HTML files produced by Asciidoctor on a webserver (public or intranet), having a path referencing your local C: is not a good idea.
It is hard to tell you what to do without knowledge of your publication/distribution toolchain.
I'm experimenting with Sphinx and ReadTheDocs (RTD) to compile my documentation on every GitHub push. Unfortunately, RTD found multiple doc/docs folders containing a conf.py file.
My repository uses git sub-modules to embed third party libraries. Some of them are also documented using Sphinx. I assume the biggest (long lasting documentation build) wins and overwrites all static HTML pages in the final RTD view.
How can I exclude or tell RTD to ignore the folders of these sub-modules:
lib/cocotb
lib/osvvm
lib/vunit
docs/source/_themes/sphinx_rtd_theme
My documentation is located here:
docs/source/conf.py
docs/source/index.rst
As far as I have found, RTD does support *.yml files, but there is no entry to define the documentation root folder.
Any ideas to solve my problem?
Inside conf.py, there is a list that looks like this
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
You can put the files you want to ignore inside it like
exclude_patterns = ["lib/cocotb", "lib/osvvm", "lib/vunit", "docs/_themes/sphinx_rtd_theme"]
Please note that here the pattern is relative to the source directory, you can put / at the beginning of each file pattern above to make this more clear.
The main documentation folder and its conf.py can be configured in the Advanced Settings tab in the per project settings.
Example value: documentation/conf.py