Proposal document and advertise sphinx API

[akhmerov]

Link to the documentation you'd like to improve

https://sphinx-design.readthedocs.io/en/latest/get_started.html#

What to improve

First of all, sphinx-design is beautiful, thanks @chrisjsewell the team for implementing this!

TL;DR: I propose to better expose the internal API of sphinx-design and encourage users implement their own semantic directives based on the sphinx-design components.

Looking at the sphinx-design rst API, I notice that it mainly implements high-level tools for implementing components. If the documentation authors use these directly, the markup of the documentation mixes the presentation with the semantics. By comparison, most if not all sphinx directives have a clear semantic meaning.

I imagine that most sites won't use the entirety of the options, but will find a few specific configurations that work for them, for example a simple self-check question could look like something along these lines:

:::{dropdown} {fas}`unverified` Check yourself: what is $d \exp x/dx$?
:animate: fade-in-slide-down
:color: info
It's $\exp x$!
:::

At the same time, the documentation author would probably rather want to write something like

:::{question} Check yourself: what is $d \exp x/dx$?
It's $\exp x$!
:::

This is straightforward to implement, and it doesn't require any reorganization from sphinx-design itself, but:

• Not all authors will come up with the idea, rather than having overly verbose and error-prone sources
• Without the sphinx API documented, the task requires a source dive.

Therefore I propose to have this use case in mind, and along with the markup corresponding to the directives and roles to document the corresponding nodes, potentially also providing a tutorial for implementing semantic components of one's own.

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[choldgraf]

I think this is a clever idea, given that sphinx-design is providing building block elements which could be composed together in a repeatable fashion. Another example of this is in my PR to the Sphinx Book Theme, where I'm basically trying to re-create the top of the front-page of Sphinx Design https://github.com/executablebooks/sphinx-book-theme/pull/370

I think there could be a fast improvement here and a longer-term improvement, both in the documentation:

• Fast improvement: Create a page like the sphinx-design gallery or sphinx-design recipes where people can add PRs that show some MyST/rST and the subsequent render, so that others can take inspiration and copy/paste
• Slow improvement: Add documentation about how people could create their own Sphinx directives that utilize sphinx-design under the hood (e.g. how to create the :::{question} directive above)

I think both wouldn't be too hard to put together and could be a cool way to boost the reach of this package

[chrisjsewell]

Thanks @akhmerov, I think in most cases this could be boiled down to a more general sphinx feature request (or just best practice): setting "global" or "modal" defaults for directive options.

One simple way to do this would be e.g.:

from sphinx_design.dropdown import DropdownDirective

class QuestionDirective(DropdownDirective):

   def set_option_default(self, name: str, value: str) -> None:
      """This should be called inside the ``run`` method."""
      self.options.setdefault(name, self.option_spec[name](value))

   def run(self):
      self.set_option_default("animate", "fade-in-slide-down")
      self.set_option_default("color",  "info")
      self.set_option_default("icon",  "unverified")
      return super().run()

def setup(app):
   app.add_directive("question", QuestionDirective)

You don't really need to know too much about the API then, like nodes etc.

I would be a little wary about promoting too much use of the low-level API though, since this implies extra "guarantees" on its stability, making it more difficult to do any refactoring/improvements to it later on.

[chrisjsewell]

Edited the code above a bit with improvements, could maybe add the set_option_default method to all the directives in sphinx design

[choldgraf]

@chrisjsewell yeah I think a big challenge here is just that the Sphinx docs are so lacking - ideally it would be easy to find an answer to "How do I sub-class a Directive in order to create one of my own".

either way I agree that if this were documented somewhere in sphinx-design it should be listed as "advanced" and with no promises that breaking changes won't mess this up.

[akhmerov]

You don't really need to know too much about the API then, like nodes etc.

Hehe, I also included {fas} as a part of the component in my example :stuck_out_tongue_closed_eyes: That does require using nodes.

Slow improvement: Add documentation about how people could create their own Sphinx directives

Mainly I meant to suggest autodocing all the classes, purely as a reference to save a code dive.

I would be a little wary about promoting too much use of the low-level API though

While I absolutely relate to the concern, having a semantic component defined in a single place is easier to maintain downstream than a whole bunch of copypasted code.

[chrisjsewell]

I also included {fas} as a part of the component in my example 😝 That does require using nodes.

Not if you use the icon option 😉 (as I added to my example code)

[chrisjsewell]

I believe this is largely solved now by #194

[akhmerov]

Thanks, the solution looks great!