Re: [Docutils-develop] [docutils:feature-requests] #91 Include directive path argument should support a configurable root.

[Karl O. P. <ko...@ka...>]

On Sun, 19 Nov 2023 21:39:11 -0000
"Günter Milde" via Docutils-develop
<doc...@li...> wrote:

> Waiting for a consensus about behaviour of image file reading (see
> comment above) …

I have not read and understood the entire thread, so apologies
if my comment here is not helpful.

When I think of a "root directory" for Sphinx I think
in terms of a webserver's "Document Root" -- the uppermost
part of the filesystem hierarchy to which the webserver
(symlinks, etc., aside) has access.

The sphinx-quickstart tool seems to make "document root" be
the directory containing the RST source directory.
The "images" and "_static" directories used by Sphinx
are placed in the same directory as the RST source directory.
(If I'm right, it's been a while since I used sphinx-build.)
So the directory containing the RST source plays the role
of "topmost part of the filesystem hierarchy" that is of
interest to Sphinx.

So, to me, it makes sense for the Sphinx "document root" to default
to the directory containing the "sourcedir" argument that is
supplied to the sphinx-build command.  This gives consistency
to the directory structures used whether it is sphinx-build
or sphinx-quickstart (and it's Makefile) that is used to
build the docs.

The question of defaults is orthogonal to the question of whether
there should be configuration directives controlling what
the "root directory" should be for various kinds of documentation
elements, images, static files, etc.  But I think it does
impact how the various root directories are specified.
It seems to me that the specification of the root directory
in the configuration file should be relative to some default
location.  To be specific, without having put in a lot of thought,
it seems that being relative to the "sourcedir" argument to
"sphinx-build" would be a good choice.  That way a single configuration
file can be re-used in different "sphinx-build" invocations
each of which has a different "sourcedir" argument.

tldr; you can stop reading now.

As an aside, I've never been comfortable with the directory
layout created by sphinx-quickstart.  I don't like the way
it mixes sphinx-quickstart created content with content
supplied by the sphinx user.  (Or that's how it feels to me.)
Of course, everything setup by sphinx-quickstart can be changed
by frobbing config.py, but I'm talking about defaults -- which
is likely the directory structure most people use.  I would love
to see a "better" default directory layout.  (And I seem to recall
that there's some single knob/argument that does something
to better separate sphinx-quickstart supplied files from
user supplied files from build directories, etc.  I think.)
What you get when you type just "sphinx-quickstart", I'm guessing
from what I've seen, seems to result in a lot of projects
putting the stuff sphinx-quickstart creates under revision
control.  Because it's simpler to put the whole directory
created by sphinx-quickstart under revision control than
to tease out what files are sphinx's and which are user-created.
Or to take the time to figure out how to use sphinx-build
or tweak the sphinx-quickstart invocation. Especially when first
using sphinx.  Putting sphinx-supplied stuff under revision
control makes it harder to use newer versions of sphinx/newer
sphinx features as they are released.  (I bit the bullet
and figured out how to use sphinx-build and am using that
instead of sphinx-quickstart and its Makefile, in my
Makefiles/whatever.) I wanted to write this paragraph to inject
some off-topic-but-related-to-directory-layout
feedback and don't expect anything to change.  Thanks for
listening and feel free to ignore this digression.

Hoping at least some of the above is useful,

Karl

> ---
> 
> **[feature-requests:#91] Include directive path argument should
> support a configurable root.**
> 
> **Status:** pending
> **Group:** Default
> **Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
> **Last Updated:** Sun Jun 25, 2023 07:01 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.



Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein