Skip to content

doc: fix layout of tables within parameter lists - #10274

Merged
QuLogic merged 3 commits into
matplotlib:masterfrom
timhoffm:css-table-in-field-list
Feb 11, 2018
Merged

QuLogic merged 3 commits into
matplotlib:masterfrom
timhoffm:css-table-in-field-list

Conversation

@timhoffm

Copy link
Copy Markdown
Member

PR Summary

Since using numpydoc, it's quite common to insert the interpolated parameter list into the "Additional Parameters" section. The css layout was not specifically great for this, because it was assuming a top-level table.

This PR adds dedicated css for tables in numpydoc field descriptions.

Before:
grafik

After:
grafik

Note: #10161 also targets the layout of interpolated parameter lists. However, the two issues are independent. The effect of #10161 is still visible in the above screenshots. Also, this PR does not influence a possible solution of #10161.

@tacaswell tacaswell added this to the v2.2 milestone Jan 21, 2018
@tacaswell

Copy link
Copy Markdown
Member

pinging @doraf who is our web design expert.

@dorafc

dorafc commented Jan 21, 2018

Copy link
Copy Markdown
Contributor

CSS seems fine. However, the legibility issues may be better resolved by pulling this info out of a table and into a definition list.

@timhoffm

Copy link
Copy Markdown
Member Author

Not sure, if a definition list is more readable, at least as long as it stays below **kwargs. Or are you proposing to remove **kwargs and inject all the parameters into "Other Parameters"?

Note, that the text above the table should be left aligned with the table. Its additional indentation is due to #10161.

@timhoffm
timhoffm force-pushed the css-table-in-field-list branch from cdc54e7 to 06d2793 Compare January 29, 2018 22:44
@timhoffm

timhoffm commented Feb 1, 2018

Copy link
Copy Markdown
Member Author

@doraf I propose to discuss the insertion of the parameters as a definition list as part of #10161. Until then, this PR is a simple improvement. I would be happy if it could go into 2.2.

@timhoffm
timhoffm requested a review from tacaswell February 1, 2018 21:13

@jklymak jklymak left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks better. Didn't check all the docs to make sure it doesn't cause other problens...

@timhoffm

timhoffm commented Feb 1, 2018

Copy link
Copy Markdown
Member Author

@jklymak Thanks for the remark. I checked that now and in fact, there are some rare cases of other tables which are affected, e.g.

old:
https://5776-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/_as_gen/matplotlib.axes.Axes.set_anchor.html#matplotlib.axes.Axes.set_anchor

new:
https://5780-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/_as_gen/matplotlib.axes.Axes.set_anchor.html#matplotlib.axes.Axes.set_anchor

(unfortunately, I've just added this table recently myself ...)

I've now augmented the code to add a class attribute property-table to the generated tables. This allows to specifcally select and style only these in css.

@timhoffm

timhoffm commented Feb 2, 2018 •

Copy link
Copy Markdown
Member Author

Hm, some strange CI failures, which I doubt are related to the PR.

  • travis seems to have some problems with wx stuff
  • appveyor couldn't clone the branch

@timhoffm
timhoffm force-pushed the css-table-in-field-list branch from cda5b22 to 912eb50 Compare February 3, 2018 11:47
@QuLogic
QuLogic merged commit 4036241 into matplotlib:master Feb 11, 2018
@QuLogic QuLogic modified the milestones: needs sorting, v2.2.0 Feb 12, 2018
@timhoffm
timhoffm deleted the css-table-in-field-list branch March 18, 2018 00:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants