Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Try wrapping section content in html classes #147

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

jnothman
Copy link
Member

@jnothman jnothman commented Nov 15, 2017

Trying to make sections stylable (i.e. putting them in HTML elements with specified classes, like numpydoc-section and numpydoc-{parameters,attributes,...}) turns out to be quite hard:

  • wrapping section headings breaks parsing of field lists, so we focus on section content (even though tooltips and link anchors on section headings would be really useful IMO)
  • using .. rst-class:: works sometimes, but labels every paragraph in an unstructured section, and does not wrap autosummary tables
  • wrapping in .. container:: (the right way to do it) adds the class container to the HTML div (this is hard-wired into docutils), which interacts with bootstrap.css
  • wrapping in .. raw:: html \n\n <div class="...."> sometimes works, sometimes doesn't. It seems that docutils sometimes closes the opened <div> automatically before the following content (this happens for definition lists, but not for an autosummary table). Looks like a bug, but I've not yet understood where it's coming from.
  • there might be a doctree-level solution, but I imagine in some cases it would involve a container node, raising the same issue as above.

This PR uses rst-class to add a class to parameter listings, as a proof of concept. Better would be to use .. container:: or equivalent (I've tried creating my own directive, but copying the existing container class doesn't help because all the writing logic is hardwired in docutils), but we need to work out a way to disable default .container styling from bootstrap, which in scipy central's theme sets width: 80%.

I thought this would be more straightforward. I'm not convinced anything in reST is straightforward.

Related: #88

@jnothman jnothman changed the title Try wrapping section content in html classes WIP: Try wrapping section content in html classes Apr 2, 2019
@larsoner
Copy link
Collaborator

larsoner commented Apr 2, 2019

wrapping in .. container:: (the right way to do it) adds the class container to the HTML div (this is hard-wired into docutils), which interacts with bootstrap.css

I wonder if those of us who use sphinx-bootstrap-theme should heed this advice:

https://sourceforge.net/p/docutils/bugs/267/#6d70

In particular, we could build into sphinx-bootstrap-theme CSS the necessary overrides to undo the docutils.container "damage" to the Boostrap container class.

Then this PR would be much simpler, right?

@larsoner
Copy link
Collaborator

larsoner commented Apr 2, 2019

... oh wait, the problem is that we would have to undo all bootstrap-related stuff to make the "container" class that gets added be a no-op in this situation. Never mind :(

Base automatically changed from master to main March 5, 2021 12:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants