search

natcap / invest.users-guide

The User's Guide for InVEST
22 stars 17 forks source link

Switch to alabaster theme #95

Closed emlys closed 2 years ago

emlys commented 2 years ago

The ReadTheDocs build is having unrelated issues, so please download the github actions artifact (here) to see what the new theme looks like.

emlys commented 2 years ago

@jagoldstein I think I've brought back the table of contents within model sections. Could you maybe attach a screenshot showing the other two points? Thanks

jagoldstein commented 2 years ago

@emlys please see the screenshot here from Chrome on Windows. Two red lines show the width of the margins relative to the content. Blue marks circle some of the many seemingly excessive examples of word splitting. alabasterThemeUG

dcdenu4 commented 2 years ago

Hey @emlys, thanks for looking into this. James mentioned that part of the motivation to do this was translation related? Could you mention what those considerations are in the PR summary?

Remove the "Supporting & Final Ecosystem Services" vs. "Additional Tools" sections of the index. Alphabetize the list of models. And change some chapter titles to match the model title.

I feel like there is some history here with those two distinct sections. If you don't mind, I think it would be worth linking this new UG theme and changes in Slack and tagging @lmandle , @adrianvogl , and @newtpatrol. The software team has become the maintainer of the Users Guide over the years, but the UG should really be driven from the science / communication side (IMO), so I just want to make sure we're not making changes in a vacuum.

Sorry if this has already been hashed out and I missed it since I've been out!

emlys commented 2 years ago

I didn't realize the title and TOC changes would be so controversial so I've removed them entirely.

The purpose of this PR is to get the free, automatic translation that comes with the standard themes. I agree with most of the style issues people have pointed out, but they're a bit far removed from the scope of the issue I'm trying to address. Would it be ok to save that for #97?

If folks would prefer one of the other built-in themes rather than alabaster, that's fine and easy to switch.

davemfish commented 2 years ago

The purpose of this PR is to get the free, automatic translation that comes with the standard themes. I agree with most of the style issues people have pointed out, but they're a bit far removed from the scope of the issue I'm trying to address. Would it be ok to save that for #97?

I agree it's nice to not get bogged down in too many details that are tangential to the goal. But I think it's worth making sure we avoid making the UG harder to use, even temporarily. To that end, I think these items are worth addressing if we can:

  • Longer titles in the sidebar are wrapped to the next line (e.g. "InVEST Scripting Guide and API"), which can be a little frustrating to read
  • The sidebar has only a very slight visual distinction from the body of the text.

I do like how all the model links are visible in the sidebar! (but you may have changed it back already, which is fine too).

But @emlys , if you do want to get on with the real task at hand and ignore all these details for now, what about merging this into a feature branch and then coming back to do the theme work later?

dcdenu4 commented 2 years ago

I didn't realize the title and TOC changes would be so controversial so I've removed them entirely. - Emily

Sorry! This is me projecting / anticipating the larger NatCap reaction from previous UG changes. Maybe it's not as controversial anymore as it once was.

The purpose of this PR is to get the free, automatic translation that comes with the standard themes. - Emily

Ah, that is important, thanks.

what about merging this into a feature branch and then coming back to do the theme work later? - Dave

This is what I was thinking as well.

dcdenu4 commented 2 years ago

Hey @emlys, I completely missed the discussion you all were having in #94, sorry about that!

emlys commented 2 years ago

The sidebar structure is now nearly the same as it was before:

image image
emlys commented 2 years ago

Thanks for catching that @dcdenu4!

jagoldstein commented 2 years ago

@emlys I'm liking the new look, but would it be possible to lock the TOC as a panel on the left so that it doesn't scroll out of view as users move down a page?

emlys commented 2 years ago

@emlys I'm liking the new look, but would it be possible to lock the TOC as a panel on the left so that it doesn't scroll out of view as users move down a page?

good idea @jagoldstein, I've moved this over to #97