Michal Urbanski

I'm fine with both. Both <> and / make sense and are a convention in some technologies. And btw, paths and URLs are both part of URIs. I would not support \, C and C++ do not support it either and I haven't seen \ as a path separator in any web tech too.

First, sorry for a late response and overall inactivity but yeah, this is what I want. Thanks. Will write to Nikola maintainers about the feature.

Yes, this sounds like a reasonable solution - an option that tells the directive to use a path relative to something configurable. Obviously the path should be specified elsewhere - otherwise the directive would be just pointless.

Yes, it's public. I'm using Nikola (https://getnikola.com/). Regarding Sphinx, I don't know much about it. Looking at it seems like it's very close to Nikola (both use conf.py, Jinja, reST and have similar build process). I don't really know if Sphinx would be better tool for my project. I choose Nikola because vast majority of static site generations (an online list I found had ~500 entries) are either exclusively for blogs or documentation and Nikola was a python-based barebone generator that offer...

All of workarounds you have listed seem dirty for me (placing various constraints on the repository, file system or something else) so I think I will have to write my own plugin for it. 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. Not really sure, this is beyond my knowledge...

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...

Using it as a marker for "project root" seems odd. Why do you think so? Absolute paths make no sense for any such project. tools/buildhtml.py and Sphinx - I'm using a different framework for building static websites. In addition, Sphinx is intended for documentation only and what I write resembles a virtual book. What I need is a format that supports somewhat rich text that is able to be transformed into HTML. reST with its extensibility (directive plugins) is the best thing I could find. I want...

reST: include directive should support root-relative paths