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

[Günter M. <mi...@us...>]

> ... What I want is `.. include:: /include/common_1` that will work
> regardless where the current article is placed.

There is no natural choice for a "project directory" in stock Docutils.
Adding a configuration setting for an "include path root" will be
considered, if there is a consensus from the frameworks adding "project"
support that this is helpful.

Open questions remain, e.g. whether to use an configurable "include path
root" only for included reStructuredText files or also for code, literal
include, and parsed includes. 
In the first case, it might be better to support a configurable list of
standard include directories.

> 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
> with it too.

Several workarounds exist with current Docutils
(none is fully clean and simple):

* Use absolute path relative to the file system, e.g.
  `.. include:: /path-to/include/common_1`.
  
  Con: long path, requires change if the complete project moves.
  Maybe a symlink can help to provide a short absolute path.
  
* Place your basic include files in
  `<docutils package root>/parsers/rst/include/`

  Con: this is an internal directory, changes with every Docutils update.

* Use symlinks in your project's sub-directories:

       project/include
       project/book1/
       project/book1/include  -> ../include

* Convince your framework to re-write absolute include path arguments     
  
* Convince your framework to use `os.chroot()`
  or [pychroot](https://pypi.org/project/pychroot/)

  Con: requires Linux, `os.chroot()` also requires "root" privileges
  May lead to problems with imports and other file access.

* Check, whether any of the existing
  [website generators](https://docutils.sourceforge.io/docs/user/links.html#website-generators-and-html-variants)
  supports an "include path root".
  
  Transfer a working solution to your framework or switch the framework
  (Sphinx, while complex and geared towards documentation, should be
  well-suited for a book project, 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:** Wed May 04, 2022 09:19 AM 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.