From 3ebdbaab4e5640cdf2a2b3db57dfc8805c40c1ad Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Wed, 22 Jan 2025 10:02:21 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20clarify=20needimport=20argument?= =?UTF-8?q?=20format?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explain the difference between local paths that are; relative to the document, relative to the source directory, absolute --- docs/directives/needimport.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/directives/needimport.rst b/docs/directives/needimport.rst index 7d0bf40bc..e7dd78b42 100644 --- a/docs/directives/needimport.rst +++ b/docs/directives/needimport.rst @@ -21,14 +21,31 @@ You can generate a valid file using the builder :ref:`needs_builder`, for exampl :pre_template: pre_template.rst :post_template: post_template.rst -The directive needs an absolute or relative path as argument. -If the path is relative, we derive an absolute path based on the location of the document being compiled. +The directive argument can be one of the following formats: -The directive also supports URL as argument to download ``needs.json`` from remote, for example: +- A remote URL from which to download the ``needs.json``: -.. code-block:: rst + .. code-block:: rst + + .. needimport:: https://my_company.com/docs/remote-needs.json + +- A local path relative to the containing document: + + .. code-block:: rst + + .. needimport:: needs.json + +- A local path starting with ``/`` is relative to the Sphinx source directory: + + .. code-block:: rst + + .. needimport:: /path/to/needs.json + +- For an absolute path, make sure to start with two ``//`` (on Linux/OSX): - .. needimport:: https://my_company.com/docs/remote-needs.json + .. code-block:: rst + + .. needimport:: //absoulte/path/to/needs.json Options -------