[Docutils-checkins] SF.net SVN: docutils:[9426] trunk/docutils

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

Revision: 9426
          http://sourceforge.net/p/docutils/code/9426
Author:   milde
Date:     2023-07-03 12:38:54 +0000 (Mon, 03 Jul 2023)
Log Message:
-----------
Small documentation fixes/additions.

Remove trailing whitespace, update links.
Add comment to structure `parsers.rst.directives` source.
Expand docstring for `utils.relative_path()`.

Modified Paths:
--------------
    trunk/docutils/docs/user/config.txt
    trunk/docutils/docutils/parsers/rst/directives/__init__.py
    trunk/docutils/docutils/utils/__init__.py

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2023-06-30 14:56:47 UTC (rev 9425)
+++ trunk/docutils/docs/user/config.txt	2023-07-03 12:38:54 UTC (rev 9426)
@@ -1237,8 +1237,9 @@
 
 A comma-separated list of paths to CSS stylesheets. Relative paths are
 expanded if a matching file is found in the stylesheet_dirs__.
-If embed_stylesheet__ is False, paths are rewritten relative to the
-output HTML file.
+If embed_stylesheet__ is False, paths are rewritten relative to
+the output HTML file (if output_ or ``<destination>`` are specified)
+or the current work directory.
 See also `stylesheet_path [latex writers]`_.
 
 Also overrides "stylesheet". [#override]_
@@ -1417,8 +1418,6 @@
 
 New in Docutils 0.18.
 
-.. _base64: https://en.wikipedia.org/wiki/Base64
-.. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
 .. _lazy loading attribute: https://html.spec.whatwg.org/multipage/
     urls-and-fetching.html#lazy-loading-attributes
 
@@ -1841,9 +1840,9 @@
 
 A comma-separated list of style files. Relative paths are expanded if a
 matching file is found in the stylesheet_dirs__.
-If embed_stylesheet__ is False, paths are rewritten relative to the
-output file path. Run ``latex`` from the directory containing
-the output file.
+If embed_stylesheet__ is False, paths are rewritten relative to
+the output file (if output_ or ``<destination>`` are specified)
+or the current work directory.
 See also `stylesheet_path [html writers]`_.
 
 For files in the `TeX input path`_, the stylesheet__  option is recommended.
@@ -2074,7 +2073,7 @@
 custom_header
 ~~~~~~~~~~~~~
 
-Specify the contents of a custom header line.  
+Specify the contents of a custom header line.
 See section "`Custom header/footers`_" in the ODT Writer documentation
 for details.
 
@@ -2085,7 +2084,7 @@
 custom_footer
 ~~~~~~~~~~~~~
 
-Specify the contents of a custom footer line.  
+Specify the contents of a custom footer line.
 See section "`Custom header/footers`_" in the ODT Writer documentation
 for details.
 
@@ -2122,9 +2121,9 @@
 ~~~~~~~~~~~~~~~
 
 Specify a configuration/mapping file relative to the current working
-directory for additional ODF options. 
+directory for additional ODF options.
 In particular, this file may contain a mapping of default style names to
-names used in the resulting output file. 
+names used in the resulting output file.
 See section `How to use custom style names`__ in the
 ODT Writer documentation for details.
 
@@ -2131,7 +2130,7 @@
 Default: None.
 Option: ``--odf-config-file``.
 
-__ odt.html#how-to-use-custom-style-names    
+__ odt.html#how-to-use-custom-style-names
 
 
 stylesheet
@@ -2143,7 +2142,7 @@
 Default: writers/odf_odt/styles.odt in the installation directory.
 Option: ``--stylesheet``.
 
-.. _styles and classes: odt.html#styles-and-classes    
+.. _styles and classes: odt.html#styles-and-classes
 
 
 table_border_thickness

Modified: trunk/docutils/docutils/parsers/rst/directives/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/__init__.py	2023-06-30 14:56:47 UTC (rev 9425)
+++ trunk/docutils/docutils/parsers/rst/directives/__init__.py	2023-07-03 12:38:54 UTC (rev 9426)
@@ -141,6 +141,12 @@
     _directives[name] = directive
 
 
+# conversion functions for `Directive.option_spec`
+# ------------------------------------------------
+#
+# see also `parsers.rst.Directive` in ../__init__.py.
+
+
 def flag(argument):
     """
     Check for a valid flag option (no argument) and return ``None``.

Modified: trunk/docutils/docutils/utils/__init__.py
===================================================================
--- trunk/docutils/docutils/utils/__init__.py	2023-06-30 14:56:47 UTC (rev 9425)
+++ trunk/docutils/docutils/utils/__init__.py	2023-07-03 12:38:54 UTC (rev 9426)
@@ -493,13 +493,21 @@
     Differences to `os.path.relpath()`:
 
     * Inverse argument order.
-    * `source` expects path to a FILE
-      while `start` in `os.path.relpath()` expects a DIRECTORY.
-      (You must add a "dummy" file name if the `source` is a directory.)
+    * `source` is assumed to be a FILE in the start directory (add a "dummy"
+      file name to obtain the path relative from a directory)
+      while `os.path.relpath()` expects a DIRECTORY as `start` argument.
     * Always use Posix path separator ("/") for the output.
     * Use `os.sep` for parsing the input
       (changing the value of `os.sep` is ignored by `os.relpath()`).
     * If there is no common prefix, return the absolute path to `target`.
+
+    Differences to `pathlib.PurePath.relative_to(other)`:
+
+    * Object oriented interface.
+    * `source` expects path to a FILE while `other` expects a DIRECTORY.
+    * No default value for `other`.
+    * Raise ValueError if relative path cannot be determined.
+    * Fails if target is not a subpath of `other` (no ".." inserted).
     """
     source_parts = os.path.abspath(source or type(target)('dummy_file')
                                    ).split(os.sep)

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.