pradyunsg / furo

A clean customizable documentation theme for Sphinx
https://pradyunsg.me/furo/quickstart
MIT License
2.76k stars 317 forks source link

support various footer configurations #225

Closed jdknight closed 3 years ago

jdknight commented 3 years ago

Adjust the injection of separators between various components of a footer to only do so when needed. This is to handle various configuration states a user may set for html_last_updated_fmt, html_show_copyright, html_show_sourcelink or html_show_sphinx.


A capture of various configuration modes:

image


Note that with the provides changes, there are two minor tweaks to be considered before accepting this change.

1) The period is purposely not injected at the end of a copyright statement. This provides flexibility for documentations which may not desire to inject a period after its statement (assuming there is no trailing content to append in the footer). For example:

image

2) The vertical spacer was omitted in these changes to opt for using the existing period entries as the separator (not including the "Show Source" entry. Below shows the existing pip documentation -- and when comping to the above figure, the difference can be observed:

image

If this is not desired, the merge request can be modified.


See also: https://github.com/pradyunsg/furo/discussions/220

pradyunsg commented 3 years ago

Thanks for filing this PR!

I like this overall. Periods are certainly less visually noisy than the pipe.

This provides flexibility for documentations which may not desire to inject a period after its statement (assuming there is no trailing content to append in the footer)

I don't think this flexibility is necessary. It's not provided today and I'm not convinced that there is a strong reason to provide it.

I'd prefer to switch to using period as the separator everywhere OR sticking to pipes everywhere.

jdknight commented 3 years ago

I don't think [optional period] flexibility is necessary.

Sure. I can adjust it to restore a fixed period character.

I'd prefer to switch to using period as the separator everywhere OR sticking to pipes everywhere.

I am good either way and am willing to make the adjustments in this pull request, if desired. I am just not sure which approach would want to be taken, as it is styling preference that I assume you would rather make the call on. From what I can tell, it could either be:

approach 1

The period-like style submitted in this pull request can be used (aside from corrections to be made, already noted above). If all pipes were to be removed, is there any other additional changes to consider for the "Show Source" section?

image

It is assumed that just removing the pipe would be fine enough; however, I did not want to make any assumptions here.

approach 2

The pipes can be restored back to its original design:

image

And the pull request can be adjusted to solely focus on the removal of the pipe characters if specific sections are disabled via the configuration.

dgw commented 3 years ago

(I am just a user of the theme but) I slightly prefer the original design with pipes. The pipeless design is great too, as long as it's consistent. (So I also agree with @pradyunsg—consistency is what's really important.)

jdknight commented 3 years ago

Adjusted the changes back to using the original pipe styling, but only applying pipes to inject if a leading section has been rendered. Example shots:

image

pradyunsg commented 3 years ago

Thanks @jdknight! ^.^