docutils-develop — For developer discussions of the implementation.

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

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

- **summary**: reST: include directive should support root-relative paths --> Include directive path argument should support a configurable root.
- **Group**: None --> Default



---

** [feature-requests:#91] Include directive path argument should support a configurable root.**

**Status:** open
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Tue May 10, 2022 09:03 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.

[Docutils-develop] [docutils:patches] #192 Codebase modernisation

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

- **status**: open --> closed-fixed
- **Comment**:

A large part of the proposed cleanups are now implemented. 
Others are outdated after the drop of 2.7 support or not agreed on.
Thanks for contributing.



---

** [patches:#192] Codebase modernisation**

**Status:** closed-fixed
**Group:** None
**Created:** Wed Jan 26, 2022 12:37 AM UTC by Adam  Turner
**Last Updated:** Tue May 03, 2022 11:13 AM UTC
**Owner:** nobody


This follows on from the Python 2.x cleanup work.

The total diff looks quite large, but the marjority of these are mechanical search / replace changes -- viewing by commit or in groups of commits may be best. 

https://github.com/AA-Turner/docutils/pull/12 // https://github.com/AA-Turner/docutils/pull/12.patch

I kept things seperate so that it would be easier to extract and rebase changes that you don't want to merge (hopefully there aren't any of these!).

A


---

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

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

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

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

For "elsewhere", I propose the [configuration settings](https://docutils.sourceforge.io/docs/user/config.html).

Before attempting a patch, we should check with the various frameworks
(Sphinx, Nicola, Pelican, ...) how useful they consider this to be
and whether we should

* provide an "include-root" for the include path, or
* provide a "standard-include-path", i.e. a list of directories to search for
   ``<angle-backeted-files>`` [standard "include" data files](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment).
  





---

** [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:** Fri May 06, 2022 10:27 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.

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

[Guenter M. <mi...@us...>]

On 2022-05-06, Michal Urbanski via Docutils-develop wrote:

> [-- Type: text/plain, Encoding: 7bit --]

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

For "elsewhere", I propose the `configuration settings`¹.

Before attempting a patch, we should check with the various frameworks
(Sphinx, Nicola, Pelican, ...) how useful they consider this to be
and whether we should

* provide an "include-root" for the include path, or

* provide a "standard-include-path" (list of directories to search for
  include files with the ``.. include:: <something>`` syntax².

Günter  
  
¹ https://docutils.sourceforge.io/docs/user/config.html
² https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment
  

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

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

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.


---

** [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 10:41 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.

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

[Adam T. <aa-...@us...>]

Would you be able to share a document structure demonstrating the problem? 

>From a brief glance, `nikola build` seems to build everything from a constant CWD, so there is no problem with changing paths.

What might be possible is an option to the `include` directive (either as a direct option or a configuration setting) that sets the CWD, perhaps

```restructuredtext
.. include::
   :use-include-root: 
```

With a configurable root location for `include`, it might alleviate your concerns about style?

A


---

** [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 06:13 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.

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

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

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 ability to be heavily customized.


---

** [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 05: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.

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

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

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 of Docutils. I can only share my experience with C and C++ build systems which do a lot of similar stuff, though the situation there is simpler from this point of view because everything there is code. Overall, I think that *there is a consensus from the frameworks adding "project" support that this is helpful* because majority of frameworks I have seen (if not all) do have a mechanism where some paths are root-relative and the framework expects certain files in certain places.




---

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

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

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

[Adam T. <aa-...@us...>]

> supplied by the framework I use

You've mentioned a framework a couple of times, what framework is it please? Is it public?

> Sphinx is intended for documentation only and what I write resembles a virtual book

Have you seen Sphinx-Book-Theme[1]? That project aims to create online book type things.

[1]: https://sphinx-book-theme.readthedocs.io/en/stable/

A


---

** [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 04:49 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.

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

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

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

Moving this to "feature-requests", as there is no patch attached.

The heading is IMO misleading: The "include" directive supports "root-relative" (i.e. absolute) paths following the conventions of Python's `open()` standard function. (It  passes the path to `open()` after resolving  the special syntax for standard “include” data files.)
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. 

Alternatives:

* Get Python's  `open()` to open paths starting with '\' relative to a "project root" in the custom build system.
* Tools like "chroot" or similar could be used on the system level to start a build system with  "project root" == "filesystem root".




---

** [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:04 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.

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

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

Ticket moved from /p/docutils/patches/193/


---

** [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:04 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.

[Docutils-develop] [docutils:patches] #193 reST: include directive should support root-relative paths

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

> 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 support for root-relative paths because it would allow me to write many articles referring to common parts that have fixed location within the repository. I can then change/reorder pages and not worry that changing their paths breaks include directive.


---

** [patches:#193] 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 05:32 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/patches/

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

[Docutils-develop] [docutils:patches] #193 reST: include directive should support root-relative paths

[Adam T. <aa-...@us...>]

`/` in a (posix) filesystem denotes the actual root, surely? Using it as a marker for "project root" seems odd.

Perhaps you could look at `tools/buildhtml.py`, or at `Sphinx`? Both allow for consistency in the CWD for when the documentation is rendered, perhaps allieviating your concern about fragility.

I don't undertand how the relative path requirements are limiting, please could you provide some more context?

A

(P.S. this should be moved to "Feature Requests" -- @milde are you able to do that? I don't think I can move it, or at least there doesn't seem to be a button.)


---

** [patches:#193] 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 04:03 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/patches/

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

[Docutils-develop] [docutils:patches] #193 reST: include directive should support root-relative paths

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

---

** [patches:#193] 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 04:03 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/patches/

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

[Docutils-develop] [docutils:patches] #192 Codebase modernisation

[Adam T. <aa-...@us...>]

There are always improvements! But this issue specifically about 2.7 cleanup I think can be closed.

A


---

** [patches:#192] Codebase modernisation**

**Status:** open
**Group:** None
**Created:** Wed Jan 26, 2022 12:37 AM UTC by Adam  Turner
**Last Updated:** Tue May 03, 2022 10:48 AM UTC
**Owner:** nobody


This follows on from the Python 2.x cleanup work.

The total diff looks quite large, but the marjority of these are mechanical search / replace changes -- viewing by commit or in groups of commits may be best. 

https://github.com/AA-Turner/docutils/pull/12 // https://github.com/AA-Turner/docutils/pull/12.patch

I kept things seperate so that it would be easier to extract and rebase changes that you don't want to merge (hopefully there aren't any of these!).

A


---

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

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

[Docutils-develop] [docutils:patches] #192 Codebase modernisation

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

Are there possible improvements left or can we close this ticket?


---

** [patches:#192] Codebase modernisation**

**Status:** open
**Group:** None
**Created:** Wed Jan 26, 2022 12:37 AM UTC by Adam  Turner
**Last Updated:** Thu Jan 27, 2022 05:24 PM UTC
**Owner:** nobody


This follows on from the Python 2.x cleanup work.

The total diff looks quite large, but the marjority of these are mechanical search / replace changes -- viewing by commit or in groups of commits may be best. 

https://github.com/AA-Turner/docutils/pull/12 // https://github.com/AA-Turner/docutils/pull/12.patch

I kept things seperate so that it would be easier to extract and rebase changes that you don't want to merge (hopefully there aren't any of these!).

A


---

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

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

[Docutils-develop] [docutils:patches] #191 Update URLs

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

- **status**: open --> closed-fixed



---

** [patches:#191] Update URLs **

**Status:** closed-fixed
**Group:** None
**Created:** Thu Jan 20, 2022 04:40 AM UTC by Adam  Turner
**Last Updated:** Fri Jan 21, 2022 05:48 PM UTC
**Owner:** nobody


Documentation / minor change. 

There are a lot of old URLs in the repo -- e.g. `docutils.sf.net`, `docutils.sourceforge.net` -- whilst these currently still work, we should update them all to the canonical `https://docutils.sourceforge.io` 

This patch does that, and also generally updates several other links to `https://` -- I tested each domain, so didn't update some old sourceforge domains that don't support `https://`. I also updated the `docutils.dtd` IDN in a single commit, so it can be dropped if wanted. 

I'd certainly reccomend applying the first 4 commits, and ideally the entire patch. 

https://github.com/AA-Turner/docutils/pull/10 // https://github.com/AA-Turner/docutils/pull/10.patch

A


---

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

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

[Docutils-develop] [docutils:patches] #183 Fix spacing around `code` and `raw` blocks in `compound` blocks

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

- **status**: open --> pending-remind



---

** [patches:#183] Fix spacing around `code` and `raw` blocks in `compound` blocks**

**Status:** pending-remind
**Group:** None
**Created:** Mon Aug 16, 2021 08:17 PM UTC by Clément Pit-Claudel
**Last Updated:** Sat Sep 11, 2021 11:40 AM UTC
**Owner:** nobody
**Attachments:**

- [1-visit-inline.patch](https://sourceforge.net/p/docutils/patches/183/attachment/1-visit-inline.patch) (2.5 kB; text/x-patch)
- [2-compound-code.patch](https://sourceforge.net/p/docutils/patches/183/attachment/2-compound-code.patch) (2.1 kB; text/x-patch)
- [3-compound-raw.patch](https://sourceforge.net/p/docutils/patches/183/attachment/3-compound-raw.patch) (766 Bytes; text/x-patch)
- [compound.rst](https://sourceforge.net/p/docutils/patches/183/attachment/compound.rst) (629 Bytes; text/x-rst)


I have attached three patches and a test related to spaces before `raw` and `code` blocks.

- `1-visit-inline.patch`: This is a small code simplification
- `2-compound-code.patch`: This removes an unconditional newline added in compound blocks before code blocks that have a `:name:`
- `3-compound-raw.patch`: This removes an unconditional newline added in compound blocks before raw blocks.
- `compound.rst`: This is a test; I wasn't sure where to add it.  It shows how things are modified by 



---

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

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

[Docutils-develop] [docutils:feature-requests] #84 Recognize syntax for optional and repeating arguments in option lists

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

- **summary**: Allow optional and repeating arguments in option lists --> Recognize syntax for optional and repeating arguments in option lists



---

** [feature-requests:#84] Recognize syntax for optional and repeating arguments in option lists**

**Status:** open
**Group:** Default
**Labels:** reStructuredText 
**Created:** Mon Nov 01, 2021 05:44 PM UTC by Alkis Georgopoulos
**Last Updated:** Mon Jan 03, 2022 08:09 AM UTC
**Owner:** nobody


The [option-lists specs](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists) state that "the syntax for short and long POSIX options is based on the syntax supported by Python's [getopt.py](https://docs.python.org/3/library/getopt.html) module".

This doesn't allow for optional or repeating arguments. A couple of examples from the [man man page](https://manpages.debian.org/bullseye/man-db/man.1.en.html#OPTIONS):

```shell
--warnings[=warnings]  This is an argument with an optional value

-m system[,...]  This is an argument with a repeating value
```

My feature request is for the square brackets `[]` to become allowed in the option lists spec and implementation in a similar way as the less than / great than symbols `<>`.

This will allow us to use docutils even when some binaries in our project do need optional or repeating arguments.
(I'm currently evaluating if it would be appropriate to migrate the https://ltsp.org and https://epoptes.org documentation and [man pages](https://ltsp.org/man/ltsp-image/), from markdown to restructuredtext)


---

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.

Re: [Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

[Guenter M. <mi...@us...>]

On 2022-04-29, Jesse Brennan via Docutils-develop wrote:

> Thank you both, that makes a lot of sense. I guess I was confused
> because I was thinking of "a link" as a reference, not a target. But if
> I understand now correctly, unless the link is anonymous, then "a link"
> is both a reference *and* a target.

A "normal" link is not a target but a link with embedded target sets up
both, a target element (identifier) and a reference to it.

The syntax

  `link name <file:target.txt>`_

is just a shorthand for ::

  `link name`_
  
  .. _link name: file:target.txt
  
This is explained in the reStructuredText specification but I assume it
feels "natural" only in hindsight.

> It sounds like the solution I'm looking for here is just making the
> link anonymous.

Another option would be to increase the report level.

Günter

[Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

[Jesse B. <jes...@us...>]

Thank you both, that makes a lot of sense. I guess I was confused because I was thinking of "a link" as a reference, not a target. But if I understand now correctly, unless the link is anonymous, then "a link" is both a reference *and* a target.

It sounds like the solution I'm looking for here is just making the link anonymous. Thanks you!

>Perhaps we could improve the error message?

If the error message suggested using an anonymous link, that would have lead me down the right path, but I understand if that's not a desirable change.


---

** [bugs:#446] Links with bracket references cause unexpected "Hyperlink target is not referenced" error**

**Status:** closed-invalid
**Created:** Thu Apr 21, 2022 07:13 PM UTC by Jesse Brennan
**Last Updated:** Fri Apr 29, 2022 02:43 PM UTC
**Owner:** nobody


I'm getting a surprising error when running reporting on a minimal RST file.

Here's the minimal.rst:
~~~
`a link <different name_>`_

.. _different name: https//www.example.com
~~~

Now if I run
~~~
rst2html.py minimal.rst --report=1 --traceback > /dev/null
minimal.rst:3: (INFO/1) Hyperlink target "a link" is not referenced.
~~~

you see the error I get. As far as I know, this is perfectly valid RST, so I'm wondering if this error message is a bug.

For more context, I encountered this error originally on a different project: https://github.com/myint/rstcheck/issues/77 which makes use of docutils.


---

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

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

[Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

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

- **status**: open --> closed-invalid
- **Comment**:

While an error message for valid input would be a bug, this is no error message:

`--report=1` requests to print all kind of information, not only errors.

INFO/1 level issues are informational -- caused by valid input, they may indicate a potential to streamline your document or make it more robust.

The embedded alias in a named hyperlink creates a new target, that is not referenced elsewhere:

> With a single trailing underscore, the reference is named and the same target URI may be referred to again. With two trailing underscores, the reference and target are both anonymous, and the target cannot be referred to again.
-- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

Adding a second underscore should silence the info, whether it is an improvement to your document depends on the context.

Thank you for reporting.



---

** [bugs:#446] Links with bracket references cause unexpected "Hyperlink target is not referenced" error**

**Status:** closed-invalid
**Created:** Thu Apr 21, 2022 07:13 PM UTC by Jesse Brennan
**Last Updated:** Fri Apr 29, 2022 03:17 AM UTC
**Owner:** nobody


I'm getting a surprising error when running reporting on a minimal RST file.

Here's the minimal.rst:
~~~
`a link <different name_>`_

.. _different name: https//www.example.com
~~~

Now if I run
~~~
rst2html.py minimal.rst --report=1 --traceback > /dev/null
minimal.rst:3: (INFO/1) Hyperlink target "a link" is not referenced.
~~~

you see the error I get. As far as I know, this is perfectly valid RST, so I'm wondering if this error message is a bug.

For more context, I encountered this error originally on a different project: https://github.com/myint/rstcheck/issues/77 which makes use of docutils.


---

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

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

[Docutils-develop] [docutils:bugs] Re: #447 docutils-cli.py not available when installing via pip

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

> This might not be an actual bug, but the behavior is surprising, and
> the documentation lead me to believe that docutils-cli.py should be
> available regardless of installation method.

> ... the command could not be found.
> Other tools were available, such as rst2html.py.

The reason is a missing entry in the `package_data['scripts']` list
in `setup.py`. This is an oversight during the recent addition of this tool.

There are plans, to overhoul the front-end tool naming and installation using
"entry points" (that allow automatic installation and leaving out the ".py"
extension also on Windows). 
In the course of this changes, the generic front-end tool
could/should be renamed from `docutils-cli.py` to `docutils`.
We may consider using the new name (and entry-point) already in 0.19.

Thank you for reporting.


---

** [bugs:#447] docutils-cli.py not available when installing via pip**

**Status:** open
**Created:** Thu Apr 21, 2022 07:19 PM UTC by Jesse Brennan
**Last Updated:** Thu Apr 21, 2022 07:19 PM UTC
**Owner:** nobody


This might not be an actual bug, but the behavior is surprising, and the documentation lead me to believe that docutils-cli.py should be available regardless of installation method.

I created a new virtual environment with Python 3.8.3. With the virtual environment active, I updated to the latest version of pip, then installed docutils.

I then tried to run docutils-cli.py but the command could not be found. Other tools were available, such as rst2html.py.


---

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

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