Skip to content

Commit 2488b7d

Browse files
choldgrafjorisvandenbossche
choldgraf
and
jorisvandenbossche
authored
Updating note color and adding docs for colors (#281)
Co-authored-by: Joris Van den Bossche <[email protected]>
1 parent 9697182 commit 2488b7d

File tree

6 files changed

+110
-75
lines changed

6 files changed

+110
-75
lines changed

‎docs/user_guide/customizing.rst

Lines changed: 43 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -7,49 +7,59 @@ Customizing the theme
77
In addition to the configuration options detailed at :ref:`configuration`, it
88
is also possible to customize the HTML layout and CSS style of the theme.
99

10+
.. _custom-css:
1011

11-
Customizing the CSS
12-
===================
12+
Custom CSS Stylesheets
13+
======================
1314

14-
The theme's CSS can be tweaked in 2 ways. The most straight forward way is to
15-
change the theme variables. If you are looking for more customisation, you can
16-
write additional css in ``custom.css``.
15+
You may customize the theme's CSS by creating a custom stylesheet that Sphinx uses to build your site.
16+
Any rules in this style-sheet will over-ride the default theme rules.
1717

18-
Theme variables
19-
---------------
18+
To add a custom stylesheet, follow these steps:
2019

21-
This theme is based on top of the basic
22-
`Bootstrap CSS variables <https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables>`__
23-
extended with some theme specific variables. An overview of all variables and
24-
every default is defined in ``/pydata_sphinx_theme/static/css/theme.css``.
20+
1. **Create a CSS stylesheet** in ``_static/css/custom.css``, and add the CSS rules you wish.
21+
2. **Attach the stylesheet to your Sphinx build**. Add the following to ``conf.py``
2522

26-
In order to change a variable, add a ``custom.css`` (see below) which updates
27-
the value of certain variables in a ``:root`` section:
23+
.. code-block:: rst
2824
29-
.. code-block:: none
25+
html_static_path = ['_static']
3026
31-
:root {
32-
--font-size-base: 17px;
33-
}
27+
html_css_files = [
28+
'css/custom.css',
29+
]
3430
35-
Important, the theme is defined with CSS variables, not SASS variables!
31+
When you build your documentation, this stylesheet should now be activated.
3632

37-
Custom stylesheet
38-
-----------------
33+
CSS Theme variables
34+
===================
3935

40-
If the theme variables are not sufficient to shape theme to you liking, you can
41-
take full control over the look and feel via a custom stylesheet. If you have a
42-
stylesheet in ``_static/css/custom.css``, adding the following to ``conf.py``
43-
will ensure this stylesheet is loaded last on top of the theme variables and the
44-
base styleheet:
36+
This theme defines several `CSS variables <css-variable-help_>`_ that can be
37+
used to quickly control behavior across your documentation.
38+
39+
These are based on top of the basic `Bootstrap CSS variables <https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables>`_
40+
extended with some theme specific variables. An overview of all variables and
41+
every default is defined in `the pydata default CSS variables file <pydata-css-variables_>`_.
4542

46-
.. code-block:: rst
43+
In order to change a variable, follow these steps:
4744

48-
html_static_path = ['_static']
45+
1. :ref:`Add a custom CSS stylesheet <custom-css>`. This is where we'll configure the variables.
46+
2. Underneath a ``:root`` section, add the variables you wish to update. For example, to update
47+
the base font size, you might add this to ``custom.css``:
48+
49+
.. code-block:: none
4950
50-
html_css_files = [
51-
'css/custom.css',
52-
]
51+
:root {
52+
--font-size-base: 17px;
53+
}
54+
55+
For a complete list of the theme variables that you may override, see the
56+
`theme variables defaults CSS file <pydata-css-variables_>`_.
57+
58+
.. important::
59+
60+
Note that these are `CSS variables <css-variable-help_>`_ and not
61+
`SASS variables <https://sass-lang.com/documentation/variables>`_.
62+
The theme is defined with CSS variables, not SASS variables!
5363

5464

5565
Replacing/Removing Fonts
@@ -86,3 +96,6 @@ often paired together, can be replaced (or removed altogether) by:
8696
}
8797
</style>
8898
{% endblock %}
99+
100+
.. _pydata-css-variables: https://github.com/pandas-dev/pydata-sphinx-theme/blob/master/pydata_sphinx_theme/static/css/theme.css
101+
.. _css-variable-help: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties

‎pydata_sphinx_theme/static/css/index.4eb26a98c046fa117c2b75e31c15adbb.css renamed to ‎pydata_sphinx_theme/static/css/index.9d12c5eb74364d5955370ddd9e2b2e85.css

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pydata_sphinx_theme/static/css/theme.css

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,11 @@
2828
**/
2929
--color-primary: 19, 6, 84;
3030
--color-success: 40, 167, 69;
31-
--color-info: 23, 162, 184;
31+
--color-info: 0, 123, 255; /*23, 162, 184;*/
3232
--color-warning: 255, 193, 7;
3333
--color-danger: 220, 53, 69;
3434
--color-text-base: 51, 51, 51;
35+
3536
--color-h1: var(--color-primary);
3637
--color-h2: var(--color-primary);
3738
--color-h3: var(--color-text-base);
@@ -57,12 +58,6 @@
5758
--color-toc-link-hover: var(--color-active-navigation);
5859
--color-toc-link-active: var(--color-active-navigation);
5960

60-
--color-admonition-primary: var(--color-primary);
61-
--color-admonition-success: var(--color-success);
62-
--color-admonition-danger: var(--color-danger);
63-
--color-admonition-warning: var(--color-warning);
64-
--color-admonition-info: var(--color-info);
65-
6661
/*****************************************************************************
6762
* Icon
6863
**/
@@ -74,4 +69,31 @@
7469
--icon-exclamation-circle: '\f06a';
7570
--icon-times-circle: '\f057';
7671
--icon-lightbulb: '\f0eb';
72+
73+
/*****************************************************************************
74+
* Admonitions
75+
**/
76+
77+
--color-admonition-default: var(--color-info);
78+
--color-admonition-note: var(--color-info);
79+
--color-admonition-attention: var(--color-warning);
80+
--color-admonition-caution: var(--color-warning);
81+
--color-admonition-warning: var(--color-warning);
82+
--color-admonition-danger: var(--color-danger);
83+
--color-admonition-error: var(--color-danger);
84+
--color-admonition-hint: var(--color-success);
85+
--color-admonition-tip: var(--color-success);
86+
--color-admonition-important: var(--color-success);
87+
88+
--icon-admonition-default: var(--icon-info-circle);
89+
--icon-admonition-note: var(--icon-info-circle);
90+
--icon-admonition-attention: var(--icon-exclamation-circle);
91+
--icon-admonition-caution: var(--icon-exclamation-triangle);
92+
--icon-admonition-warning: var(--icon-exclamation-triangle);
93+
--icon-admonition-danger: var(--icon-exclamation-triangle);
94+
--icon-admonition-error: var(--icon-times-circle);
95+
--icon-admonition-hint: var(--icon-lightbulb);
96+
--icon-admonition-tip: var(--icon-lightbulb);
97+
--icon-admonition-important: var(--icon-exclamation-circle);
98+
7799
}

‎pydata_sphinx_theme/static/js/index.3edd59071b60732de7f5.js renamed to ‎pydata_sphinx_theme/static/js/index.f77e788ac4de8d0ef24c.js

File renamed without changes.

‎pydata_sphinx_theme/static/webpack-macros.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@
1717

1818
{% macro head_pre_bootstrap() %}
1919
<link href="{{ pathto('_static/css/theme.css', 1) }}" rel="stylesheet" />
20-
<link href="{{ pathto('_static/css/index.4eb26a98c046fa117c2b75e31c15adbb.css', 1) }}" rel="stylesheet" />
20+
<link href="{{ pathto('_static/css/index.9d12c5eb74364d5955370ddd9e2b2e85.css', 1) }}" rel="stylesheet" />
2121
{% endmacro %}
2222

2323
{% macro head_js_preload() %}
24-
<link rel="preload" as="script" href="{{ pathto('_static/js/index.3edd59071b60732de7f5.js', 1) }}">
24+
<link rel="preload" as="script" href="{{ pathto('_static/js/index.f77e788ac4de8d0ef24c.js', 1) }}">
2525
{% endmacro %}
2626

2727
{% macro body_post() %}
28-
<script src="{{ pathto('_static/js/index.3edd59071b60732de7f5.js', 1) }}"></script>
28+
<script src="{{ pathto('_static/js/index.f77e788ac4de8d0ef24c.js', 1) }}"></script>
2929
{% endmacro %}

‎src/scss/_admonitions.scss

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
overflow: hidden;
77
page-break-inside: avoid;
88
border-left: 0.2rem solid;
9-
border-color: rgba(var(--color-admonition-primary), 1);
9+
border-color: rgba(var(--color-admonition-default), 1);
1010
border-radius: 0.1rem;
1111
box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05),
1212
0 0 0.05rem rgba(0, 0, 0, 0.1);
@@ -33,17 +33,17 @@
3333
margin: 0 -0.6rem !important;
3434
padding: 0.4rem 0.6rem 0.4rem 2rem;
3535
font-weight: 700;
36-
background-color: rgba(68, 138, 255, 0.1);
36+
background-color: rgba(var(--color-admonition-default), 0.1);
3737

3838
&:before {
3939
position: absolute;
4040
left: 0.6rem;
4141
width: 1rem;
4242
height: 1rem;
43-
color: rgba(var(--color-admonition-primary), 1);
43+
color: rgba(var(--color-admonition-default), 1);
4444
font-family: 'Font Awesome 5 Free';
4545
font-weight: 900;
46-
content: var(--icon-info-circle);
46+
content: var(--icon-admonition-default);
4747
}
4848

4949
// Next element after title needs some extra upper-space
@@ -53,25 +53,25 @@
5353
}
5454

5555
&.attention {
56-
border-color: rgba(var(--color-admonition-warning), 1);
56+
border-color: rgba(var(--color-admonition-attention), 1);
5757
.admonition-title {
58-
background-color: rgba(var(--color-admonition-warning), 0.1);
58+
background-color: rgba(var(--color-admonition-attention), 0.1);
5959

6060
&:before {
61-
color: rgba(var(--color-admonition-warning), 1);
62-
content: var(--icon-exclamation-circle);
61+
color: rgba(var(--color-admonition-attention), 1);
62+
content: var(--icon-admonition-attention);
6363
}
6464
}
6565
}
6666

6767
&.caution {
68-
border-color: rgba(var(--color-admonition-warning), 1);
68+
border-color: rgba(var(--color-admonition-caution), 1);
6969
.admonition-title {
70-
background-color: rgba(var(--color-admonition-warning), 0.1);
70+
background-color: rgba(var(--color-admonition-caution), 0.1);
7171

7272
&:before {
73-
color: rgba(var(--color-admonition-warning), 1);
74-
content: var(--icon-exclamation-triangle);
73+
color: rgba(var(--color-admonition-caution), 1);
74+
content: var(--icon-admonition-caution);
7575
}
7676
}
7777
}
@@ -83,7 +83,7 @@
8383

8484
&:before {
8585
color: rgba(var(--color-admonition-warning), 1);
86-
content: var(--icon-exclamation-triangle);
86+
content: var(--icon-admonition-warning);
8787
}
8888
}
8989
}
@@ -95,67 +95,67 @@
9595

9696
&:before {
9797
color: rgba(var(--color-admonition-danger), 1);
98-
content: var(--icon-exclamation-triangle);
98+
content: var(--icon-admonition-danger);
9999
}
100100
}
101101
}
102102

103103
&.error {
104-
border-color: rgba(var(--color-admonition-danger), 1);
104+
border-color: rgba(var(--color-admonition-error), 1);
105105
.admonition-title {
106-
background-color: rgba(var(--color-admonition-danger), 0.1);
106+
background-color: rgba(var(--color-admonition-error), 0.1);
107107

108108
&:before {
109-
color: rgba(var(--color-admonition-danger), 1);
110-
content: var(--icon-times-circle);
109+
color: rgba(var(--color-admonition-error), 1);
110+
content: var(--icon-admonition-error);
111111
}
112112
}
113113
}
114114

115115
&.hint {
116-
border-color: rgba(var(--color-admonition-warning), 1);
116+
border-color: rgba(var(--color-admonition-hint), 1);
117117
.admonition-title {
118-
background-color: rgba(var(--color-admonition-warning), 0.1);
118+
background-color: rgba(var(--color-admonition-hint), 0.1);
119119

120120
&:before {
121-
color: rgba(var(--color-admonition-warning), 1);
122-
content: var(--icon-lightbulb);
121+
color: rgba(var(--color-admonition-hint), 1);
122+
content: var(--icon-admonition-hint);
123123
}
124124
}
125125
}
126126

127127
&.tip {
128-
border-color: rgba(var(--color-admonition-info), 1);
128+
border-color: rgba(var(--color-admonition-tip), 1);
129129
.admonition-title {
130-
background-color: rgba(var(--color-admonition-info), 0.1);
130+
background-color: rgba(var(--color-admonition-tip), 0.1);
131131

132132
&:before {
133-
color: rgba(var(--color-admonition-info), 1);
134-
content: var(--icon-lightbulb);
133+
color: rgba(var(--color-admonition-tip), 1);
134+
content: var(--icon-admonition-tip);
135135
}
136136
}
137137
}
138138

139139
&.important {
140-
border-color: rgba(var(--color-admonition-info), 1);
140+
border-color: rgba(var(--color-admonition-important), 1);
141141
.admonition-title {
142-
background-color: rgba(var(--color-admonition-info), 0.1);
142+
background-color: rgba(var(--color-admonition-important), 0.1);
143143

144144
&:before {
145-
color: rgba(var(--color-admonition-info), 1);
146-
content: var(--icon-exclamation-circle);
145+
color: rgba(var(--color-admonition-important), 1);
146+
content: var(--icon-admonition-important);
147147
}
148148
}
149149
}
150150

151151
&.note {
152-
border-color: rgba(var(--color-admonition-info), 1);
152+
border-color: rgba(var(--color-admonition-note), 1);
153153
.admonition-title {
154-
background-color: rgba(var(--color-admonition-info), 0.1);
154+
background-color: rgba(var(--color-admonition-note), 0.1);
155155

156156
&:before {
157-
color: rgba(var(--color-admonition-info), 1);
158-
content: var(--icon-info-circle);
157+
color: rgba(var(--color-admonition-note), 1);
158+
content: var(--icon-admonition-note);
159159
}
160160
}
161161
}

0 commit comments

Comments
 (0)