Menu
▾
▴
#69 Allow sidebar directive to have no title
The sidebar directive currently requires a positional argument (the "title") due to inheriting from the PseudoSection (https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/parsers/rst/directives/body.py#l63). I feel there are many use-cases where a user would want to add a sidebar, but not add a title with it. Would it be possible to make the title an optional argument for the sidebar directive?
Can you provide examples of such use cases in the wild?
I think one good example is from the "Edward Tufte CSS" website:
https://edwardtufte.github.io/tufte-css/
They make liberal use of sidenotes as a kind of alternative to footnotes.
That site is also (IMO) a worthwhile one to emulate
from a web-based publishing perspective.
We also use sidebars in this way on a project that I'm working on (
https://jupyterbook.org/intro) and that many other
people have used to build their own online books. It doesn't currently use
docutils, but I am hoping to transition the
codebase to use docutils under the hood.
(note that I think there are also plenty of reasons to want a title for
the sidebar, I just don't think it's always needed)
Chris
On Thu, Mar 19, 2020 at 6:21 PM David Goodger goodger@users.sourceforge.net
wrote:
Related
Feature Requests:
#69This would be really great to have for a book I'm working on right now.
I agree that this would be helpful as a generic container for block elements in the margin
(side-figures, quotes, annotations, admonitions, ...) in cases where no footnote-like reference/label is
required. (Otherwise, just style footnotes as sidenotes.)
Real world example: the nicely designed "Kulturgeschichte der Physik" by K. Simonyi
https://scilogs.spektrum.de/uhura-uraniae/simonyi-kulturgeschichte-der-physik/
https://openlibrary.org/books/OL24579545M/A_cultural_history_of_physics
The following patch is a possible implementation of "sidebar title optionalisation":
--- a/docutils/docutils/parsers/rst/directives/body.py
+++ b/docutils/docutils/parsers/rst/directives/body.py
@@ -36,16 +36,20 @@ class BasePseudoSection(Directive):
raise self.error('The "%s" directive may not be used within '
'topics or body elements.' % self.name)
self.assert_has_content()
- title_text = self.arguments[0]
- textnodes, messages = self.state.inline_text(title_text, self.lineno)
- titles = [nodes.title(title_text, '', *textnodes)]
- # Sidebar uses this code.
- if 'subtitle' in self.options:
- textnodes, more_messages = self.state.inline_text(
- self.options['subtitle'], self.lineno)
- titles.append(nodes.subtitle(self.options['subtitle'], '',
- textnodes))
- messages.extend(more_messages)
+ if self.arguments: # title (in sidebars optional)
+ title_text = self.arguments[0]
+ textnodes, messages = self.state.inline_text(title_text, self.lineno)
+ titles = [nodes.title(title_text, '', *textnodes)]
+ # Sidebar uses this code.
+ if 'subtitle' in self.options:
+ textnodes, more_messages = self.state.inline_text(
+ self.options['subtitle'], self.lineno)
+ titles.append(nodes.subtitle(self.options['subtitle'], '',
+ textnodes))
+ messages.extend(more_messages)
+ else:
+ titles = []
+ messages = []
text = '\n'.join(self.content)
node = self.node_class(text, *(titles + messages))
node['classes'] += self.options.get('class', [])
@@ -64,6 +68,8 @@ class Sidebar(BasePseudoSection):
option_spec = BasePseudoSection.option_spec.copy()
option_spec['subtitle'] = directives.unchanged_required
@@ -71,6 +77,10 @@ class Sidebar(BasePseudoSection):
if isinstance(self.state_machine.node, nodes.sidebar):
raise self.error('The "%s" directive may not be used within a '
'sidebar element.' % self.name)
+ if 'subtitle' in self.options and not self.arguments:
+ raise self.error('The "subtitle" option may not be used '
+ 'without a title.')
+
return BasePseudoSection.run(self)
Solved in r8524.
Thank you for the suggestion.
wow, thanks so much! That's really exciting :-)
Fixed in Docutils 0.17.
Thank you for the suggestion.