Enable text wrapping in table cells (addresses #1262) #1272
Conversation
ASCII arrows can get split in half by word-wrapping
Turning on wrapping in the theme leaves decisions on column widths up to the Sphinx formatter. It does an OK job sometimes, other times the tables are imbalanced. Column widths can be manually specified by using the explicit `.. table:` directive, using its `:widths:` option. (Table code itself is the same, but has to be nested inside the `.. table:` directive, requiring the entire table block be indented five spaces. Not ideal, but it's what works.) Width syntax is... complex. If specified for all columns out of 100, then they appear to effectively be percentages. Widths can be left out for some columns (on the right of the table), and they will be defaulted. But that computation involves some sort of Sphinx magic. If we have a three-column table, `:widths: 5 25` (with the third column unspecified) will _not_ be laid out the same as `:widths: 5 25 70`. I've allowed Sphinx to default column widths where possible, but when things got weird or unpredictable I specified explicit widths for all columns.
|
@frednyc - Awesome, man! I hope Mr. Thomas gets back to this soon. And even more than that, I hope you keep on contributing to this project. You're the man, good sir! 👍 |
Which I shall set aside, as it seems that this isn't the time to be worrying about the documentation. |
|
@ferdnyc - I think OpenShot could use any help in any aspect, to become a better Video Editor. |
|
Thanks! Merged |
|
@ferdnyc - Good sir, you'd perhaps want to go through the remaining half of the tables. 😄 |
|
There's no reason the remaining tables need to be modified, we don't want to specify column widths on them. They could be modified just for consistency's sake, I suppose, even though they don't need to use any As I said, one of the advantages of But embedding those directives in the current ASCII-art tables would be... ugly, to say the least. With |
|
@ferdnyc - I think you should provide some screenshots - samples that will be convincing enough to make a move towards list-table, good sir. :) |
|
Makes sense. I'll file a new Issue with the proposal. Give me a few days.
End of the week hopefully, end of the weekend at the latest.
…On Mon, Mar 5, 2018 at 11:02 PM, peanutbutterandcrackers < ***@***.***> wrote:
@ferdnyc <https://github.com/ferdnyc> - I think you should provide some
screenshots - samples that will be convincing enough to make a move towards
list-table, good sir. :)
[And I really appreciate your efforts. You're awesome! Honestly.]
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1272 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAg1pKziqioGCI4ZqaF3mwViebrVecZcks5tbgpXgaJpZM4SBrQE>
.
|
|
Whoa! @ferdnyc is a Contributor, too, now. Awesome! Now you get to label issues and stuff. Looking forward to your proposal. 👍 |
Heh. No, turns out that's just Github's auto-label indicating I've had code committed to the project. No special powers, just a piece of flare. |
|
Oh... I see. Hmm. |
This does not happen by default in sphinx-rtd-theme. Solution copied from OpenShot/openshot-qt#1272
This does not happen by default in sphinx-rtd-theme. Solution copied from OpenShot/openshot-qt#1272
Here's the change promised in #1262, to enable text wrapping in table cells (disabled by default in the Read The Docs theme for Sphinx). It's two simple changes and one... not so simple. It turns out, having table cells wrap is a deceptively complex thing. (And I now understand the theme's reluctance to just enable wrapping by default, though I can't say I like their solution of forcing side-scrolling tables everywhere any better.)
The issue, basically, is how the cell widths are balanced by Sphinx. Sometimes it makes OK decisions. Other times, the columns are wildly imbalanced, requiring intervention by the author to get the tables sized correctly. So, after enabling wrapping, I went through the entire manual, looked at all of the tables, and manually adjusted them to what I felt was a reasonable balance by manually specifying widths for some or all columns.
Doing that is the difference between this (the default output, with wrapping enabled):
And this (manually adjusted to make the second column wider):
Note that that's the "full-width" formatting, or the "starting point" for column sizing. Even with explicit column widths, Sphinx's tables are flexible and will resize. With the browser window reduced to half the screen width, those become (respectively):
On my phone (Samsung Galaxy S6, Chrome browser) they end up looking identical, because the columns compress to the same state regardless of the specified widths.
(Honestly, while I know that one of these is a screenshot from my "unadjusted" export of the docs, and the other is the output with my column-width fixes applied, I'm really not sure which of these is which! They are, as I said, identical.)
Really, I think it does quite a good job, especially once the widths are tweaked as needed.
Now, here's the slightly bad news. The trick to doing this, as I explain in the commit message for the third (large) commit, is to use reStructuredText's explicit
.. table::directive, as it can be provided with a:widths:argument specifying column widths. When using.. table::, the table syntax is the same, but the table gets nested below the directive, requiring a 5-space indent. So this table (from the repo HEAD):Becomes this (after my patch):
It's not ideal, but it's not unworkable. Using
.. table::does also give us the option of converting to.. list-table::format, which dumps the ASCII art and turns that code into:...and so on.
There are definite advantages to that format, especially as the column contents get more complex, and especially especially if they end up containing RST markup. (That's something else I'd like to explore at a later date, as I have some thoughts in that area.) So, if we want to convert the doc tables to
.. list-table::formatting, then that's a possibility for a future PR. The rendered table is the same, so it's purely an issue of source readability.Oh, I made one other change (as you'll see in the second commit), to replace the ASCII arrows (
->) used at a couple of points in the tables (and body text) with real Unicode → arrows. That was purely an aesthetic decision, as word-wrapping would cause the ASCII arrows to get split in half sometimes. (e.g:)which will instead now be (worst-case):