#69 Allow sidebar directive to have no title

[Chris Holdgraf]

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?

[David Goodger]

Can you provide examples of such use cases in the wild?

[Chris Holdgraf]

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:

Can you provide examples of such use cases in the wild?

• [feature-requests:#69]
  https://sourceforge.net/p/docutils/feature-requests/69/ Allow sidebar
  directive to have no title*

Status: open
Group: Default
Created: Fri Mar 20, 2020 12:15 AM UTC by Chris Holdgraf
Last Updated: Fri Mar 20, 2020 12:15 AM UTC
Owner: nobody

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?

---

Sent from sourceforge.net because you indicated interest in
https://sourceforge.net/p/docutils/feature-requests/69/

To unsubscribe from further messages, please visit
https://sourceforge.net/auth/subscriptions/

[Andreas Mueller]

This would be really great to have for a book I'm working on right now.

[Günter Milde]

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):

  node_class = nodes.sidebar

• required_arguments = 0

• optional_arguments = 1
  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)

[Günter Milde]

Solved in r8524.
Thank you for the suggestion.

[Chris Holdgraf]

wow, thanks so much! That's really exciting :-)

[Günter Milde]

Fixed in Docutils 0.17.
Thank you for the suggestion.