Inherent sphinx base css

[Blendify]

This adds https://github.com/sphinx-doc/sphinx/blob/master/sphinx/themes/basic/static/basic.css_t to our css stack. There might be some side effects so we will have to look at this carefully before merging.

Fix #746

[polyzen]

Resolves my issue, and everything looks good in my simple wiki.

[polyzen]

Seems like this needs to be assigned so it can be reviewed and merged.

[polyzen]

With this, the paragraph icon is inserted just before the anchor icon. Taking a screenshot of hovered elements is too much of a pain, but hopefully this gets the point across:

Important &amp; urgent<a class="headerlink" href="#important-urgent" title="Permalink to this headline">¶</a>

[lesteve]

Is there something that could be done to help this PR merged? I completely understand the PR as it stands (i.e. including sphinx basic.css) is a far-reaching change that could have hard-to-detect side-effects.

Maybe a less intrusive change would be to add this to your CSS (diff from sphinx-doc/sphinx#5976) instead?

.classifier:before {
    font-style: normal;
    margin: 0.5em;
    content: ":";
}

As I mentioned in #766 (comment), this would fix the most problematic issue amongst all the Sphinx 2 related issues in sphinx_rtd_theme.

Impact of this issue

Python projects that use sphinx_rtd_theme are affected by this in their auto-generated API doc. This missing delimiter can be very confusing: for example in #766 it looks like the parameter is called eta_efloat instead of eta_e (which is of type float):

Here are a few projects I could find that were affected by this (I would guess there are a significantly more):

• Argument and its type joined in docs pydata/xarray#3056
• Fix spacing between parameter and parameter type in the API docs dask/dask-jobqueue#301, Types are appended to parameters in docstring dask/dask-ml#512 and more generally all dask organization projects since dask_sphinx_theme inherit from sphinx_rtd_theme. There is an issue about this in the dask-sphinx-theme repo: Fix parameter : type merger with CSS change dask/dask-sphinx-theme#14.
• Sphinx HTML formatting missing colon in parameters gammapy/gammapy#2164
• Ugly docstrings generated by Sphinx fatiando/harmonica#58

In all cases above, we have experienced sphinx users (most have used sphinx for years in their projects for their documentation) that have to spend some significant effort to understand where the problem comes from, numpydoc vs sphinx vs sphinx_rtd_theme, and figure out which fix is the least bad of them.

Side-comment: some projects are pinning sphinx < 2 to avoid the problem, except that this is not possible on ReadTheDocs, at least last time I checked, see readthedocs/readthedocs.org#3829 for more details.

[Blendify]

Requesting review, hope this helps, we really need to get sphinx 2.0 support figured out here.

[agjohnson]

Why extend the base CSS? Wouldn't it be better to fix our styles so that display is correct with the HTML5 writer?

[Blendify]

My understanding is the base css is just "basic" styling for sphinx styling. I.e. `.. centered::` text is centered and the like. This should save us time for writing styling for individual derivatives and instead focus on the theme as a whole.

…

On Tue, Sep 24, 2019 at 4:56 PM Anthony ***@***.***> wrote: Why extend the base CSS? Wouldn't it be better to fix our styles so that display is correct with the HTML5 writer? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#747?email_source=notifications&email_token=ADT2423V53OBGV55NQSYRZDQLJ5HVA5CNFSM4HFGLSQKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7PY3VQ#issuecomment-534744534>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ADT242YRA2BRG3H4I3OJSXDQLJ5HVANCNFSM4HFGLSQA> .

-- Aaron Carlisle Project administrator for the Blender 3D Documentation Project Email: [email protected] Website: https://blendify.github.io

[agjohnson]

I'd rather treat these display issues as bugs with our CSS. Using the base CSS as a mask for these issues would also potentially open up the theme to CSS display issues caused by upstream CSS and CSS changes. Having two layers of CSS rules would also make work on our theme harder, as we don't have independent CSS rules applied anymore, we have to be concerned about two layers of CSS and how selector load order and specificity affect display. There are a few cases for keeping our CSS independent I think, so I'm more enthusiastic about resolving the html5 writer issues with our own CSS fixes.

[jessetan]

I'm +0 on this. While I do like the idea of inheriting Sphinx CSS so that we can benefit from their fixes without manually updating the theme, it does open up the risks described by @agjohnson where we need to work in the other direction: fixing things that broke when we inherited Sphinx' CSS.

Right now the pain of adding Sphinx 2 is limited to a few cases that we can handle manually, although I'll be the first to admit that it is a hassle. If we have many such issues in future, for instance because Sphinx CSS changes more rapidly, inheriting will be the best way.

[agjohnson]

That might be a good compromise. If we continue to hit issues with the base Sphinx after we address some of the Sphinx 2/HTML5 inconsistencies, we should probably consider extending the Sphinx base css at that point.

It is a hassle, but I do agree that it doesn't seem like we have a wild number of inconsistencies to address. With vacations last month, I just didn't have time to start fixes for the issues we identified. Working on the theme is on my roadmap this month however, so I'll be poking these issues or helping other with them.

[agjohnson]

I made quick progress on CSS that supports Sphinx 1.x and 2.x. I'm going to close this PR as I think it's adding more variability into our styles compared to explicitly fixing the issues.

[lesteve]

I made quick progress on CSS that supports Sphinx 1.x and 2.x.

Great to hear! Can you confirm the work you are referring to is in #838 ?