Menu
I have some code and data samples I copy to _static directory and I would like to link to those files in documentation, something like:
.. _pca-run.py: _static/example.data But the problem is that sphinx does not create a proper relative link to this file, but just copies the values as it is. So for nested files where _static is not in the same directory links do not work.
519
The toctree directive is the central element. Note. Simple “inclusion” of one file in another can be done with the include directive.
You can install Sphinx directly from a clone of the Git repository. This can be done either by cloning the repo and installing from the local clone, on simply installing directly via git. $ git clone https://github.com/sphinx-doc/sphinx $ cd sphinx $ pip install .
To support Markdown-based documentation, Sphinx can use MyST-Parser. MyST-Parser is a Docutils bridge to markdown-it-py, a Python package for parsing the CommonMark Markdown flavor.
The configuration file is executed as Python code at build time (using importlib.import_module (), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.
When you build your documentation, Sphinx will generate an inventory of all explicit and implicit links called objects.inv. You can list all of these targets to explore what is available for you to reference. Where <link> is either a URL or a local path that points to your inventory file (usually in _build/html/objects.inv ).
That way, you can load an extension called extname from the subdirectory sphinxext. The configuration file itself can be an extension; for that, you only need to provide a setup () function in it. The file extensions of source files. Sphinx considers the files with this suffix as sources.
Where <link> is either a URL or a local path that points to your inventory file (usually in _build/html/objects.inv ). For example, to see all targets from the Read the Docs documentation: You can reference to docs outside your project too! See Link to Other Projects’ Documentation With Intersphinx.
What you want is the :download: text role. (as Mitar mentioned in his comment).
https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html#role-download
Using this will tell Sphinx to copy the given file to a "_downloads" directory and create a hyperlink to it. This was originally intended to be used for downloadable files, like perhaps PDFs (in html output) or tarballs, or whatever. It works just fine for any other non-ReST file though.
If you really wanted, you could write an extension to do this, but I've never seen a need to, since :download: does exactly what I want.
185
Just find the right answer to this for images: preprend the path of the target file with /. For images referenced from an automodule
.. image:: some_file.png will refer to the file some_file.png relative to the python file currently being processed, while
.. image:: /some_file.png will refer to the file some_file.png relative to the location of the conf.py. This way, there is no need to pollute the source hierarchy with images.
25
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
