[Docutils-develop] [docutils:feature-requests] #91 reST: include directive should support root-relative paths

[Michal U. <xev...@us...>]

> Mind that for most Docutils front-end tools (rst2html, rst2latex, ...), there is no notation of a "project root".
> From the description, I guess the you may want a way to specify a "root directory" that differs from the file system's root. This would require a new configuration setting.

Fine. I have no knowledge on the configuration, majority is probably supplied by the framework I use, not docutils.

> Get Python's open() to open paths starting with '\' relative to a "project root" in the custom build system.

How? First time I'm hearing something like this.

> Get Python's open() to open paths starting with '\' relative to a "project root" in the custom build system.

No. This is definitely beyond the project. It should not require external system tools like this to support the build.

To illustrate my problem:

- (root project dir)
  - include
    - common_1   
  - book_foo
    - article_1
    - article_2
  - book_bar
    - article_1
    - article_2
    - subsection_1
      - article_1

Suppose that `book_bar/subsection_1/article_1` wants to include `include/common_1`. Currently I need to use something like `.. include:: ../../include/common_1`. This results in very fragile article code - during writing I move them quite often. If at any point I would like to reorganize articles, include paths will break. What I want is `.. include:: /include/common_1` that will work regardless where the current article is placed.

The solution does not necessarily have to be a new feature. If there is a way I can achieve such behavior e.g. through reST plugin, I'm fine wih it too.


---

** [feature-requests:#91] reST: include directive should support root-relative paths**

**Status:** open
**Group:** None
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Tue May 03, 2022 10:51 PM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.