Allow sidebar directive to have no title [SF:feature-requests:69]

[chrisjsewell]

author: choldgraf
created: 2020-03-20 00:15:27.975000
assigned: None
SF_url: https://sourceforge.net/p/docutils/feature-requests/69

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?

---

commenter: goodger
posted: 2020-03-20 01:21:52.376000
title: #69 Allow sidebar directive to have no title

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

---

commenter: choldgraf
posted: 2020-03-20 02:58:08.347000
title: #69 Allow sidebar directive to have no title

attachments:

• https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/e950ea620e/4019/89d3/attachment/alternate

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 [email protected]
wrote:

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

• [feature-requests:latex2e writer cannot render table contains multirows well [SF:bugs:44] #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/

---

commenter: t3kcit
posted: 2020-05-19 16:17:58.131000
title: #69 Allow sidebar directive to have no title

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

---

commenter: milde
posted: 2020-05-20 08:22:33.869000
title: #69 Allow sidebar directive to have no title

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)
  

---

commenter: milde
posted: 2020-07-10 10:09:06.290000
title: #69 Allow sidebar directive to have no title

• status: open --> open-fixed

---

commenter: milde
posted: 2020-07-10 10:09:07.305000
title: #69 Allow sidebar directive to have no title

Solved in r8524.
Thank you for the suggestion.

---

commenter: choldgraf
posted: 2020-07-12 14:57:33.979000
title: #69 Allow sidebar directive to have no title

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