[sphinx-proof style review][geom_series] remark_admonition

[longye-tian]

trafficstars

Dear John @jstac, Matt @mmcky

This pull request is for #442.

I reviewed all current QuantEcon intro lecture series. There are four lectures that contain remarks. Here is a summary:

• geom_series.md
• money_inflation.md
• unpleasant.md
• money_inflation_nonlinear.md

This pull request uses the geom_series.md lecture as an example to test the current admonition style.

Best ❤️ Longye

[netlify[bot]]

✅ Deploy Preview for taupe-gaufre-c4e660 ready!

Name	Link
🔨 Latest commit	c281cdb45002021a369cc9848811e98e9156ccda
🔍 Latest deploy log	https://app.netlify.com/sites/taupe-gaufre-c4e660/deploys/66e3f14ad9bccf0008c9888f
😎 Deploy Preview	https://deploy-preview-493--taupe-gaufre-c4e660.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[mmcky]

thanks @longye-tian this will be a big help. We can work on updating sphinx-proof styles.

Are you familiar with any html/css? If you are we could link up and I can show you where to submit a PR with suggested style updates. But no worries if not.

[longye-tian]

thanks @longye-tian this will be a big help. We can work on updating sphinx-proof styles.

Are you familiar with any html/css? If you are we could link up and I can show you where to submit a PR with suggested style updates. But no worries if not.

Hi Matt,

No worries. I'm not familiar with the html and css.

Best, Longye

[github-actions[bot]]

🚀 Deployed on https://66e3f341f0e44dd09b38ef1f--taupe-gaufre-c4e660.netlify.app

[mmcky]

thanks @longye-tian.

This is what the current styling is.

@jstac I propose that sphinx-proof adopts just a thin colour bar on the left hand side of the block. Any thoughts or recommendations in colour choices to represent remark?

[jstac]

Any thoughts or recommendations in colour choices to represent remark

How about green similar to the numbers in

[mmcky]

@jstac is this closer to what you're thinking?

I will see if I can match the icon colour to the line colour as well.

I have setup https://github.com/executablebooks/sphinx-proof/pull/106 to do a full review so that we can make all admonitions follow a similar minimal styling approach. I will need to define unique colours for all types of admonitions and style them all by a thin LHS line.

[jstac]

Looks great @mmcky , many thanks.

[mmcky]

• [x] will merge once https://github.com/executablebooks/sphinx-proof/pull/106 is merged and released
• [x] update config to include proof_minimal_theme: True

[mmcky]

• [x] test improvements to sphinx-proof package

[mmcky]

@DrDrij can I get your advise here.

I have just updated sphinx-proof with new styling around the sphinx-proof admonitions, however it looks like quantecon-book-theme is overriding the title style with a background colour to show

instead of

Our theme has

  .admonition {
    font-size: 0.9rem;
    margin: 1.5rem auto;
    padding: 0 1rem 0.5rem 1rem;
    page-break-inside: avoid;
    box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.1),
      0 0 0.05rem rgba(0, 0, 0, 0.1);

    .admonition-title {
      position: relative;
      margin: 0 -1rem;
      padding: 0.25rem 2rem;
      font-weight: 700;
      background-color: #0072bc26;
    }
  }

and it makes sense for it to be the main "style" here but it is quite general.

Is the best solution here to update sphinx-proof to pre-pend an admonition name that is less generic so instead of using admonition-title we should use proof-admonition-title. I guess the downside of this is that it becomes harder for "themes" to override the style.

Otherwise, we could update our own theme to use a transparent background for admonition-title for consistency across the lecture.

[DrDrij]

@mmcky Hey Matt I notice that the admonition has the proof class <div class="proof remark admonition" id="remark-0">.

So we could style it specifically such as:

div.remark.proof {
   border-color: green;
   .admonition-title {
     background-color: transparent;
   }
 }

Not sure if I have answered your question correctly though. :)

[mmcky]

thanks @DrDrij so this is what we have in sphinx-proof

/*********************************************
* Remark *
*********************************************/
div.remark {
	border-color: var(--remark-border-color);
	background-color: none;
}

div.remark p.admonition-title {
	background-color: transparent;
}

but the title in this preview has a background colour that I think is coming from quantecon-book-theme?

maybe transaparent is allowing the quantecon-book-theme underneath?

[DrDrij]

Ah I see! Yes I made a mistake.

div.remark p.admonition-title {
	background-color: transparent;
}

Will override the CSS I wrote above. CSS weighting is sequentially - element, id, class, then order. So I am adjusting the CSS I wrote from:

div.remark.proof {
   border-color: green;
   .admonition-title {
     background-color: transparent;
   }
 }

To:

div.remark.proof {
   border-color: green;
   p.admonition-title {
     background-color: transparent;
   }
 }

This way it will override regardless of order loaded on client side since it has 1 more class of specificity.

[mmcky]

@DrDrij my target is to get no background colour -- as a minimal theme supplied by sphinx-proof. I used transparent so it would match the background colour of the page but it looks like the blue background is coming through from quantecon-book-theme instead.

[mmcky]

@DrDrij I made the suggested change in https://github.com/executablebooks/sphinx-proof/pull/109 but it is still showing the blue background from quantecon-book-theme. Not sure how to override that style.

[DrDrij]

@mmcky I hope this is a reasonable request to make small changes to quantecon-book-theme and sphinx-proof to allow the styling of the admonition title background without having to force styles (using !important). I think it is best to do it properly.

https://github.com/executablebooks/sphinx-proof/pull/111

https://github.com/QuantEcon/quantecon-book-theme/pull/248

So what these changes involve is having each stylesheet (pydata, qe theme, and sphinx proof) all style the admonition title the same way. This means the ultimate background colour style will come from whichever stylesheet is loaded last in the chain. Which looks like proof.css.

[mmcky]

love your work @DrDrij

I will make new releases of:

• quantecon-book-theme, and
• sphinx-proof

then we will have minimal styles for all those admonitions such as remark.

[mmcky]

thanks @longye-tian -- Would you mind to update the other lectures with remark admonitions and then we can merge this PR.

[longye-tian]

thanks @longye-tian -- Would you mind to update the other lectures with remark admonitions and then we can merge this PR.

Hi Matt @mmcky ,

I have updated the remark admonitions for these lectures. I'll have a look on other lectures to see if there is any new lectures that need remark admonitions.

Best, Longye