From f5e62bfc036dde2f1acb6554e7012e3eb5c2d37f Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Mon, 27 Jan 2025 10:31:12 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20clarify=20`needimport`=20argumen?= =?UTF-8?q?t=20format=20(#1384)?= 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 -------