Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9409] trunk/docutils
|
From: <mi...@us...> - 2023-06-26 17:48:50
|
Revision: 9409
http://sourceforge.net/p/docutils/code/9409
Author: milde
Date: 2023-06-26 17:48:39 +0000 (Mon, 26 Jun 2023)
Log Message:
-----------
Warn the user if the S5 writer cannot copy the theme files.
Print a warning if the S5 theme files cannot be copied to the
destination dir because the output destination path is unknown to the writer.
Update documentation.
Modified Paths:
--------------
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/slide-shows.txt
trunk/docutils/docs/user/tools.txt
trunk/docutils/docutils/writers/s5_html/__init__.py
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-06-26 17:48:28 UTC (rev 9408)
+++ trunk/docutils/docs/user/config.txt 2023-06-26 17:48:39 UTC (rev 9409)
@@ -424,7 +424,7 @@
output
------
-The name of the output destination. Use ``-`` for stdout.
+The path of the output destination. Use ``-`` for stdout.
Obsoletes the ``<destination>`` positional argument
(cf. `Future changes`_ in the RELEASE-NOTES).
Modified: trunk/docutils/docs/user/slide-shows.txt
===================================================================
--- trunk/docutils/docs/user/slide-shows.txt 2023-06-26 17:48:28 UTC (rev 9408)
+++ trunk/docutils/docs/user/slide-shows.txt 2023-06-26 17:48:39 UTC (rev 9409)
@@ -18,8 +18,8 @@
of the s5_html.py writer and the ``rst2s5`` front end.
To view this document as a slide show see
- https://docutils.sourceforge.io/docs/user/slide-shows.s5.html (or `your
- local copy <slide-shows.s5.html>`__).
+ https://docutils.sourceforge.io/docs/user/slide-shows.s5.html or `your
+ local copy <slide-shows.s5.html>`__.
.. contents::
:class: handout
@@ -69,7 +69,7 @@
.. class:: handout
- ``rst2s5`` is a Docutils_ front end that outputs HTML for use
+ rst2s5_ is a Docutils_ front end that outputs HTML for use
with S5_, a "Simple Standards-based Slide Show System" by Eric
Meyer.
@@ -115,11 +115,13 @@
A variety of themes are available. See `Example Themes`_, below.
-* ``rst2s5``
+* rst2s5_
.. class:: handout
The console script to generate S5 slide shows.
+
+ .. _rst2s5: tools.html#rst2s5
.. topic:: Keyboard Controls
:class: handout
@@ -361,17 +363,22 @@
2. Run the command::
- rst2s5 slides.txt slides.html
+ rst2s5 slides.txt --output=slides.html
-3. Specify an S5 theme with the ``--theme`` option.
+3. Optionally, specify an S5 theme with the ``--theme`` option.
.. class:: handout
Docutils will copy the S5 theme files into a ``ui/<theme>`` folder
- beside the output HTML file. A slide show can also link to an
- existing theme using the ``--theme-url`` option.
+ beside the output HTML file. [#copy-theme]_ A slide show can also link
+ to an existing theme using the ``--theme-url`` option.
+ .. [#copy-theme] Theme files can only be copied by Docutils, if the
+ output_ destination path is specified.
+
+ .. _output: config.html#output
+
Generating a Slide Show (2)
===========================
Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt 2023-06-26 17:48:28 UTC (rev 9408)
+++ trunk/docutils/docs/user/tools.txt 2023-06-26 17:48:39 UTC (rev 9409)
@@ -234,7 +234,7 @@
For example, to process a reStructuredText file "``slides.txt``" into
S5/HTML::
- rst2s5 slides.txt > slides.html
+ rst2s5 slides.txt --output=slides.html
Now open the "``slides.html``" file in your favorite browser, switch
to full-screen mode, and enjoy the results.
@@ -247,14 +247,15 @@
Each S5 theme consists of a directory containing several files:
stylesheets, JavaScript, and graphics. These are copied into a
-``ui/<theme>`` directory beside the generated HTML. A theme is chosen
+``ui/<theme>`` directory beside the generated HTML. [#copy-theme]_
+A theme is chosen
using the "``--theme``" option (for themes that come with Docutils) or
the "``--theme-url``" option (for themes anywhere). For example, the
"medium-black" theme can be specified as follows::
- rst2s5 --theme medium-black slides.txt > slides.html
+ rst2s5 --theme medium-black slides.txt --output=slides.html
-The theme will be copied to the ``ui/medium-black`` directory.
+The theme will be copied [#copy-theme]_ to the ``ui/medium-black`` directory.
Several themes are included with Docutils:
@@ -324,6 +325,10 @@
For details, please see `Easy Slide Shows With reStructuredText & S5
<slide-shows.html>`_.
+.. [#copy-theme] Theme files can only be copied by Docutils, if the
+ output_ destination path is specified.
+
+.. _output: config.html#output
buildhtml.py
------------
Modified: trunk/docutils/docutils/writers/s5_html/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/s5_html/__init__.py 2023-06-26 17:48:28 UTC (rev 9408)
+++ trunk/docutils/docutils/writers/s5_html/__init__.py 2023-06-26 17:48:39 UTC (rev 9409)
@@ -9,7 +9,6 @@
__docformat__ = 'reStructuredText'
-
import sys
import os
import re
@@ -154,7 +153,10 @@
html4css1.HTMLTranslator.__init__(self, *args)
# insert S5-specific stylesheet and script stuff:
self.theme_file_path = None
- self.setup_theme()
+ try:
+ self.setup_theme()
+ except docutils.ApplicationError as e:
+ self.document.reporter.warning(e)
view_mode = self.document.settings.view_mode
control_visibility = ('visible', 'hidden')[self.document.settings
.hidden_controls]
@@ -193,15 +195,15 @@
self.theme_files_copied = {}
required_files_copied = {}
# This is a link (URL) in HTML, so we use "/", not os.sep:
- self.theme_file_path = '%s/%s' % ('ui', settings.theme)
- if settings._destination:
- dest = os.path.join(
- os.path.dirname(settings._destination), 'ui', settings.theme)
- if not os.path.isdir(dest):
- os.makedirs(dest)
- else:
- # no destination, so we can't copy the theme
- return
+ self.theme_file_path = 'ui/%s' % settings.theme
+ if not settings.output:
+ raise docutils.ApplicationError(
+ 'Output path not specified, you may need to copy'
+ ' the S5 theme files "by hand" or set the "--output" option.')
+ dest = os.path.join(
+ os.path.dirname(settings.output), 'ui', settings.theme)
+ if not os.path.isdir(dest):
+ os.makedirs(dest)
default = False
while path:
for f in os.listdir(path): # copy all files from each theme
@@ -209,7 +211,7 @@
continue # ... except the "__base__" file
if (self.copy_file(f, path, dest)
and f in self.required_theme_files):
- required_files_copied[f] = 1
+ required_files_copied[f] = True
if default:
break # "default" theme has no base theme
# Find the "__base__" file in theme directory:
@@ -249,14 +251,14 @@
def copy_file(self, name, source_dir, dest_dir):
"""
Copy file `name` from `source_dir` to `dest_dir`.
- Return 1 if the file exists in either `source_dir` or `dest_dir`.
+ Return True if the file exists in either `source_dir` or `dest_dir`.
"""
source = os.path.join(source_dir, name)
dest = os.path.join(dest_dir, name)
if dest in self.theme_files_copied:
- return 1
+ return True
else:
- self.theme_files_copied[dest] = 1
+ self.theme_files_copied[dest] = True
if os.path.isfile(source):
if self.files_to_skip_pattern.search(source):
return None
@@ -273,9 +275,9 @@
dest_dir[dest_dir.rfind('ui/'):].encode(
sys.getfilesystemencoding())))
settings.record_dependencies.add(source)
- return 1
+ return True
if os.path.isfile(dest):
- return 1
+ return True
def depart_document(self, node):
self.head_prefix.extend([self.doctype,
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
