Update the BeeWare website - WIP #578

kattni · 2024-08-02T00:24:57Z

Hello! This is my initial update to the BeeWare website. It's nowhere near completed but I wanted to get this PR in early for your perusal. So far I've done at least the following:

Split About into multiple pages and moved the link to the header
Moved the "More than just code" section of About to /community/
Moved the Code of Conduct to the header
Added a dropdown to the header so we can include more information there without overwhelming the header
Moved Membership to / and updated the link
Moved the team list to the About page
Moved the Overview from Project to About
Moved the "What can you do to help?" page into /contributing/
Everything under /how/ is now under /contributing/ and linked in the text on that page, as well as the right gutter
Moved "Core team, and responsibilities" to /community/
(As well as the obligatory) and more!

I did not check the "documented" box below because I did not keep track of everything I did, as many things were merged and separated, and I started to lose track of where it all began. The list above covers most of it, but I'm sure I missed something.

Next steps

Update Projects to showcase Briefcase and Toga, and highlight the other active tools as per discussion with @freakboy3742
Move inactive apps to Attic
Create separate contact pages for Security, Code of Conduct, etc
Continue to streamline everything else.

That's what I have for now. Cheers!

PR Checklist:

All new features have been tested
All new features have been documented
I have read the CONTRIBUTING.md file
I will abide by the code of conduct

…-website

kattni · 2024-08-03T23:58:44Z

I restructured the Project page as discussed. It looks like a lot of changes, but it's primarily renames, as I had to move everything around to restructure things.

Notes:

I am certain there is probably a better way to do what I did in the Jinja, but it works! That said, please provide any feedback you have on doing this differently, etc.
I did the best I could with sorting through the data model files and figuring out what needed to go where. Let me know if I should have done anything differently there as well.
I feel like I missed one thing that you wanted to be considered an "Application" and not a "Utility". Please let me know if the Utilities and Application categories are correct.
The /project/ page currently has very basic CSS for the purpose of differentiating divs. I didn't dig into that yet because I want you to let me know if the layout and concept are what you're looking for before I jump into styling.
I updated the /project/ page title to "BeeWare Tools". "Tools" is growing on me as a replacement for "Project" in the header and as the page name. Let me know what you think.
Toga and Briefcase are displayed through an autogenerated group of "showcased" projects (through Jinja set, for, etc), so if you want to include more later, it's a checkbox in Lektor.
I ended up having to hard-code the "Applications" and "Utilities" category boxes, because I couldn't figure out a way to generate separate lists underneath the headers if I autogenerated the categories as well. Adding another category later would mean duplicating a block of code in "beeware.html", and updating a few references to the category name and URL. I don't know if I missed something about how those groups are generated that would have allowed me to differentiate them in the code. So if there's a simpler way to do this, I'm open to it, but this was what I figured out.
The /project/utilities page has no text content as of yet. There are a lot of places where I think text needs to be updated, so we can address this when it makes sense.
The "project-type.ini" and "project-type.html" files are now only used by Attic. I meant to rename them to "attic.*" before pushing, but now I figure it's worth asking whether this makes sense before doing it. As-is, it is confusing as to what they are for, but I don't know whether they are linked to anything else in Lektor etc, and I don't want to inadvertently break things in the quest for clarity.
I updated the "Projects" section on the homepage to show only showcased projects (which are now only Toga and Briefcase).
At the moment, the original /project/projects/ directory structure is a series of empty directories prepped for redirects. I intend to add redirects when we're closer to completed in case things move around in the meantime.
I am making a note here for myself as well: I will have questions about cleaning up labels and other behind-the-scenes stuff that isn't being used anymore, as to whether things should be left in place for posterity/structure purposes or be cleaned up.

github-actions · 2024-08-04T01:18:34Z

Visit the preview URL for this PR (updated for commit ea4e70a):

https://beeware-org--pr578-streamline-beeware-w-h9imfohd.web.app

_{(expires Sun, 11 Aug 2024 01:18:10 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: b0da44bc067e7d9a4255c77cb2c5fce572218cec}

freakboy3742

Definitely a good first pass at a re-org. The broad structural changes match what we've discussed in Discord; a couple of high-level notes based on poking around:

I'm not sure about the data mode change introducing the new "important" model. It seems like that model should either (a) be a boolean flag on the existing project model, or (b) an instance of an "important" project type
The box-and-background-color layout doesn't really work IMHO. I've got some ideas on other possible approaches, but I'm not sure of the best way to share ideas/iterate on mockups of a final layout - open to suggestions on how best to collaborate on this.
Re-ordering the menubar items. It seems to me that "About" should either come much earlier, or much later (I'd lean towards earlier)
I'm wondering if the "More" item is actually achieving its desired goal. I guess the intention is to surface more to the top level without crowding the menubar... but it feels a bit like we're still crowding the menu bar, just putting it under a fold. I wonder if, instead of having a "more" item, we move those items under other headings (e.g., say, "code of conduct" under "community"), and then make the other headings pull down menus that provide shortcuts to notable "deep" content.
I think there's still some re-org potential in the contributions page. The collapse of the depth is great - but the Contribute landing page is now a bit busy and unfocussed.

If you want to catch up for a follow up chat on any of this, I'm at your disposal.

freakboy3742 · 2024-08-04T03:08:26Z

assets/static/beeware.css

+ul.dark-menu .nav-item {
+  padding: 5px 0 5px 0 !important;
+}
+


The language selection is already a pulldown, with a style; why do we need a separate style here? (or, if the issue is dark mode vs light mode - why isn't the fix making the language pulldown style dark?)

I assumed there was a reason for the background color of the language puilldown, and didn't want to change it. Fixing the language pulldown is a much better solution.

The language dropdown has been updated to match the rest of the theme.

freakboy3742 · 2024-08-04T03:57:07Z

assets/static/beeware.css

+
+.important {
+  background-color: lightgrey;
+}


I'm not wild about the use of background colours here - it feels really busy, and the box layout doesn't seem to scale well to phone-sized layouts. I wonder if it might be better to stick to a single column with icons on the side, but with bigger icons for the "featured" apps.

I updated the page to match this concept. I'll be pushing that update shortly.

For what it's worth, the background colors were solely for me to differentiate the divs so I knew where everything ended up. They were not necessarily destined for the final product.

models/important.ini

freakboy3742 · 2024-08-04T04:36:48Z

content/project/utilities/python-apple-support/contents.lr

@@ -6,7 +6,7 @@ maturity: beta
 ---
 platforms: macOS, iOS, tvOS, watchOS
 ---
-project_type: support
+project_type: utility
 ---
 short_description: A meta-package for building a version of Python that can be embedded into a macOS, iOS, tvOS or watchOS project.
 ---


Mental note that if we're going to highlight this package (and I think we should), I should probably provide some copy so that this isn't an incomplete stub.

content/project/utilities/rubicon/contents.lr

kattni · 2024-08-04T17:58:40Z

This update addresses only the Project page layout, and the issue with an unnecessary data model being added. I will address the rest of the comments/concerns/suggestions later.

freakboy3742 · 2024-08-05T00:09:42Z

content/project/contents.lr

+---
+utilities_description: These are utilities.
+---
+utilities_title: Utilities


Seems like these fields should be a description on the child project type, rather than specifically enumerated here.

I couldn't figure out how to make that work this entire time, until I was falling asleep last night, and it clicked. It now uses the information from the category page instead of duplicating it in the Project page.

kattni · 2024-08-05T21:54:14Z

Replies to your initial notes:

The box-and-background-color layout doesn't really work IMHO. I've got some ideas on other possible approaches, but I'm not sure of the best way to share ideas/iterate on mockups of a final layout - open to suggestions on how best to collaborate on this.

I pushed the update yesterday to match your later suggestion. Please let me know what you think, and if it still doesn't work for you, we can sort out a collaboration method.

Re-ordering the menubar items. It seems to me that "About" should either come much earlier, or much later (I'd lean towards earlier)

I shifted it between "Project" and "Community". Let me know if that works for you or if you want it to come first.

I'm wondering if the "More" item is actually achieving its desired goal. I guess the intention is to surface more to the top level without crowding the menubar... but it feels a bit like we're still crowding the menu bar, just putting it under a fold. I wonder if, instead of having a "more" item, we move those items under other headings (e.g., say, "code of conduct" under "community"), and then make the other headings pull down menus that provide shortcuts to notable "deep" content.

I can work this up and we can see how it feels. I think the way it works right now, the dropdown would always show up when you clicked the page link, as the page loaded, e.g. if you clicked "Community", you would load that page and see the dropdown at the same time. I'll see if I can figure out a different approach if that ends up seeming awkward, such as the dropdown only showing up if you click the arrow next to the page title or something of that nature.

I think there's still some re-org potential in the contributions page. The collapse of the depth is great - but the Contribute landing page is now a bit busy and unfocussed.

Agreed entirely. I have not taken a pass at this page yet, other than to shift contribution-related things to it.

If you want to catch up for a follow up chat on any of this, I'm at your disposal.

This would be appreciated. I'll reach out on Discord when I get to a point where it makes sense again.

kattni · 2024-08-07T19:33:34Z

The most recent update is a demo of individual existing headers having dropdown menus attached. The way it's done at the moment, the page of the header loads separately from the dropdown, which I think is a necessity.

@freakboy3742 Let me know if you like this better than the "More" menu, and we can make use of it where it makes sense moving forward. The current dropdown items are not necessarily where they will end up - I split them up to where they are for the purpose of this demo.

kattni · 2024-08-08T23:15:56Z

The most recent update implements collapsing content on the Contributing page, as a potential option for including more information, in a cleaner, less busy way, without loading up another load of subpages. I did not do it for the entire page, as this is simply meant to show what it could look like, if you are interested.

freakboy3742 · 2024-08-09T02:40:38Z

The box-and-background-color layout doesn't really work IMHO. I've got some ideas on other possible approaches, but I'm not sure of the best way to share ideas/iterate on mockups of a final layout - open to suggestions on how best to collaborate on this.

I pushed the update yesterday to match your later suggestion. Please let me know what you think, and if it still doesn't work for you, we can sort out a collaboration method.

Definitely better.

The underlining on H1 titles is overkill; we're not using underlines anywhere else, so we can probably lose them. If this has been done to make the section headings stand out a bit more, this might be an area where having a background color block on the title might make sense - although that would also be inconsistent with other parts of the website.
I'm not sure the description of project types is adding anything. As it stands, it's making the layout busier, and it's not clear how they fit into the overall flow.
While the section headings are hyperlinks, there's no real call to action to suggest why this might be the case. There might be value in having an "... and N others" hyperlink after all the featured items in a section.
The explainer of "Beeware is a suite of tools etc etc" needs to exist; I'm guessing what might be what you're intending with the "copy here" section, but I don't know if it might fit better into the sidebar. The sidebar might also be a way to maintain a link to the attic without needing to give it placement in the "main" list.

Re-ordering the menubar items. It seems to me that "About" should either come much earlier, or much later (I'd lean towards earlier)

I shifted it between "Project" and "Community". Let me know if that works for you or if you want it to come first.

I think it makes sense to be first. Unless you're coming to the project already knowing what Toga and Briefcase are, your first questions are likely to be "what is this thing?".

I'm wondering if the "More" item is actually achieving its desired goal. I guess the intention is to surface more to the top level without crowding the menubar... but it feels a bit like we're still crowding the menu bar, just putting it under a fold. I wonder if, instead of having a "more" item, we move those items under other headings (e.g., say, "code of conduct" under "community"), and then make the other headings pull down menus that provide shortcuts to notable "deep" content.

I can work this up and we can see how it feels. I think the way it works right now, the dropdown would always show up when you clicked the page link, as the page loaded, e.g. if you clicked "Community", you would load that page and see the dropdown at the same time. I'll see if I can figure out a different approach if that ends up seeming awkward, such as the dropdown only showing up if you click the arrow next to the page title or something of that nature.
...
The most recent update is a demo of individual existing headers having dropdown menus attached. The way it's done at the moment, the page of the header loads separately from the dropdown, which I think is a necessity.

@freakboy3742 Let me know if you like this better than the "More" menu, and we can make use of it where it makes sense moving forward. The current dropdown items are not necessarily where they will end up - I split them up to where they are for the purpose of this demo.

I think the menus work organisationally (better than "more", anyway); but I'm not sure the implementation is quite right. The expansion arrow is a small target, and it took me a couple of tries to get it to work. The i18n dropdown is a "click to open dropdown, click to select target"; I think that might be a better approach for about and community as well.

The most recent update implements collapsing content on the Contributing page, as a potential option for including more information, in a cleaner, less busy way, without loading up another load of subpages. I did not do it for the entire page, as this is simply meant to show what it could look like, if you are interested.

Yeah - definitely not a fan of expansion for content. IMHO it's the worst of both worlds - requires an extra click to navigate, but doesn't simplify the page when it's visible.

freakboy3742 · 2024-08-21T01:46:22Z

Following up from a conversation on Discord: here's a mockup of what I had in mind for the design of the project page. It's not that far removed from what is there right now:

Ignore the top bar menu; this is for the purely for the purposes of the project landing page. I'm also certain there's inconsistencies in exact spacing and font choice by virtue of using a mockup tool; the intention is to highlight clear space between the three "sections", and "more featured" content being larger/more prominent. Other than that, the major changes are:

Using the sidebar for the explainer/context; and including the attic as an link in that content
Making the icons more prominent, which gives a bit more space for text around them (which I think helps with the general layout)
Making the text explaining Apps and Utils more cohesive as a "featuring... and more!" kind of flow
I've filled in some of the placeholder content that hopefully fills in the gaps, and should be compatible with the existing data model (although you might need to play some tricks, like having ", including:" be static content appended to the database content)

I'm also not completely tied to any of this - if you've got ideas on how this could be improved, I'm all ears.

kattni · 2024-08-22T23:05:13Z

@freakboy3742 I have a couple of questions/suggestions before I push the current state of things.

It seems like "Project" should be called "Tools", but that does lead to other updates needed. I'm referring to the page and to the actual header menu name. Let me know what you think. I'm already doing a boatload of redirects, so another one is negligible. The translations would have to be updated though.
I updated the data model for the Applications/Utilities page to have a "Project Page Description" that is the longer-form description. Using all the content except "including" as the "short description" seemed a bit long as a page description under the header on the page itself. So I added another field to the page to add the longer-form version. If this is not acceptable, let me know. (If you want to wait until I push to see what I'm talking about, that's also fine. But I think my description is enough to explain why I opted to do something you suggested against - and that is why I am bringing it up here.)
There is only one "application". I currently have it so that it checks how many items exist in the project query, and if it is more than 1, it includes the "..... and others", otherwise, it does not. I feel like "and others" when there is one is a bit clunky and odd, but let me know if you disagree and would rather it simply be hardcoded to be there no matter what.

Everything else we discussed is more or less in place and updated. These are a few items we did not discuss, so I wanted to bring them up before continuing.

freakboy3742 · 2024-08-23T04:31:03Z

@freakboy3742 I have a couple of questions/suggestions before I push the current state of things.

It seems like "Project" should be called "Tools", but that does lead to other updates needed. I'm referring to the page and to the actual header menu name. Let me know what you think. I'm already doing a boatload of redirects, so another one is negligible. The translations would have to be updated though.

I'm not sure about this one. To me, "tools" are the things that you actually touch to do things - so Briefcase might be a tool - but a library or template or support package is something else... it's not really a "tool". The existing text on the project page reinforces that kind of distinction - "BeeWare isn't a single tool or library - it's a collection of projects". To that end "Project" (or maybe "Projects") would seem to be the better fit.

I updated the data model for the Applications/Utilities page to have a "Project Page Description" that is the longer-form description. Using all the content except "including" as the "short description" seemed a bit long as a page description under the header on the page itself. So I added another field to the page to add the longer-form version. If this is not acceptable, let me know. (If you want to wait until I push to see what I'm talking about, that's also fine. But I think my description is enough to explain why I opted to do something you suggested against - and that is why I am bringing it up here.)

That sounds perfectly reasonable to me - it's nice if we can re-use content when we can, but we don't have to be completely dogmatic about it for the sake of "database minimalism".

There is only one "application". I currently have it so that it checks how many items exist in the project query, and if it is more than 1, it includes the "..... and others", otherwise, it does not. I feel like "and others" when there is one is a bit clunky and odd, but let me know if you disagree and would rather it simply be hardcoded to be there no matter what.

Podium is the only application on the current website taxonomy; but Cricket, Bugjar, Duvet, and Galley would all fit under the category of "Application" rather than "Utility" to my mind, as they're end-user apps. That should still leave plenty of content for the utilities page.

kattni · 2024-08-27T18:41:42Z

Redirect script wasn't quite right. Fixing.

Streamline beeware website

kattni · 2024-08-27T21:00:24Z

@freakboy3742 This should now be much closer to where we discussed. I've removed the functional menu changes, and moved the discussed items into appropriate locations. The Project page now better reflects your mockup.

A couple of notes:

The Utilities page needs a "long-form description", by which I mean, the content that goes in the gutter (grey sidebar box). The Applications page has one, I think it makes sense to have on Utilities, but I do not know what to include for that content.
The Bee Team page is not rendering the team photos for me locally; I don't know if this is because I moved it and missed something tied to it, or for a similar reason that the icons for the social media things don't render (e.g. they render when the site actually builds, but not on the lektor server version). Let me know if I missed something here and have an item to fix with it.

Please take a look when you get a chance, and let me know what you think.

freakboy3742

Nice work - this is looking really good. This looks like it's converging on a really solid re-organization of the current website content, without trying to fix the universe in one push.

We're definitely into the "tweaking the minor details" stage - the big structural stuff is looking great. Some things I noticed:

It looks like pages that had image resources (e.g., Headshot links on /about/team; media resources on /about/contact/media, screenshots on /contributing/first-time/github) are broken; it looks like the body content is pointing to the old image location.
There's a bunch of links in content to /community/team in body content (e.g., on the /about/contact page). They're all redirecting correctly to the new location; but it should be possible to fix with a search-and-replace. If you've got a list of redirects that you've added, it's likely worth doing a similar search and replace for those.
Some fine tuning of the CSS on the project page is needed. If you compare the layout of the "/project/utilities" page:

to the layout of the equivalent section on the "/project" page:

the icon is a little bigger, and there's less padding on top of the title, which means the description text fits hanging under the title, rather than falling under the icon; and there's a small gap between the icon and the text. This is most noticeable on Rubicon, because the icon is a full square. * I *think* there's some cleanup required around the data models and templates tied to the project pages. I flagged the generic nature of "beeware.html/beeware.ini" in an inline comment; but I think that's part of this general problem - that there's still pieces of older "deep nested" data model in the repo after the refactor. The real marker of this is that we're removing a layer of depth/complexity, but *adding* a data model... at the very least, I would have expected to see one data model removed, if not more than one.

The last two points are definitely on the more complex end of the scale; if you don't feel sufficiently confident in your CSS/Lektor wrangling to tackle either of those, let me know, and I'm happy to get my hands dirty. The Lektor one in particular is making my brain melt a bit 😄 - mostly because I need to refresh my memory on how the model, template, and directory structure interact.

freakboy3742 · 2024-08-27T23:38:27Z

content/community/behavior/code-of-conduct/contents.lr


 ---
 summary: All participants in the BeeWare community are expected to adhere to a Code of Conduct
 ---
 gutter:

+`Making a Code of Conduct Report </code-of-conduct/making-a-coc-report/>`__


This is renders fine, but the underline is weirdly long, and the link seems to be a 404.

Also, I wonder if it might be better to have the heading not be a link, and add the link to the call to action "Here's how to report the situation".

The /code-of-conduct/... link is used consistently across this page.

freakboy3742 · 2024-08-28T00:06:29Z

templates/layout.html

@@ -82,13 +82,13 @@
  </div>
  <div class="collapse navbar-collapse" id="navbarsDefault">
    <ul class="navbar-nav mr-auto">
+      {{ menu_item('about') }}
      {{ menu_item('project') }}


Should this be Project or Projects?

freakboy3742 · 2024-08-28T00:19:17Z

models/beeware.ini

The name of this model threw me for a bit. It looks almost identical to project-type; but the name is a lot more "generic". It looks like it might be tied to the historical use of beeware.html as a template, but that template used to be a lot more generic than it is now.

kattni added 2 commits July 31, 2024 16:42

Move About Beeware to header.

9ddf2ca

Rearrange Project, Community, Contributing, About

24517ed

kattni changed the title ~~Update the BeeWare website~~ Update the BeeWare website - WIP Aug 2, 2024

Merge remote-tracking branch 'beeware/lektor' into streamline-beeware…

93fc294

…-website

kattni force-pushed the streamline-beeware-website branch from 942edce to 93fc294 Compare August 3, 2024 17:10

Project page restructured. Still needs CSS.

ea4e70a

freakboy3742 added the preview Approved for an automated preview label Aug 4, 2024

freakboy3742 reviewed Aug 4, 2024

View reviewed changes

Update Project layout, remove superfluous model

830b7fb

freakboy3742 reviewed Aug 5, 2024

View reviewed changes

Properly obtain category titles and descriptions.

48c9d9c

Update Rubicon page, shift About link

f4ed371

kattni force-pushed the streamline-beeware-website branch from 5e4ade5 to 4f8584b Compare August 9, 2024 19:32

kattni force-pushed the streamline-beeware-website branch from 4f8584b to f4ed371 Compare August 22, 2024 21:56

Shuffle apps, add sort, redirects.

a4d8f88

kattni force-pushed the streamline-beeware-website branch from 5bb6856 to a4d8f88 Compare August 27, 2024 18:40

jepler and others added 3 commits August 27, 2024 13:42

add redirects by script

85b64cf

Fix doubly redirected pages by script

2f5615b

Merge pull request #2 from jepler/streamline-beeware-website

46cecc5

Streamline beeware website

Remove old_path from existing redirects.

533463a

freakboy3742 requested changes Aug 28, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update the BeeWare website - WIP #578

Update the BeeWare website - WIP #578

kattni commented Aug 2, 2024

kattni commented Aug 3, 2024 •

edited

Loading

github-actions bot commented Aug 4, 2024

freakboy3742 left a comment

freakboy3742 Aug 4, 2024

kattni Aug 4, 2024

kattni Aug 7, 2024

freakboy3742 Aug 4, 2024

kattni Aug 4, 2024

kattni Aug 4, 2024

freakboy3742 Aug 4, 2024

kattni commented Aug 4, 2024

freakboy3742 Aug 5, 2024

kattni Aug 5, 2024

kattni commented Aug 5, 2024

kattni commented Aug 7, 2024

kattni commented Aug 8, 2024

freakboy3742 commented Aug 9, 2024

freakboy3742 commented Aug 21, 2024

kattni commented Aug 22, 2024

freakboy3742 commented Aug 23, 2024

kattni commented Aug 27, 2024

kattni commented Aug 27, 2024

freakboy3742 left a comment

freakboy3742 Aug 27, 2024

freakboy3742 Aug 27, 2024

freakboy3742 Aug 28, 2024

freakboy3742 Aug 28, 2024

Update the BeeWare website - WIP #578

Are you sure you want to change the base?

Update the BeeWare website - WIP #578

Conversation

kattni commented Aug 2, 2024

Next steps

PR Checklist:

kattni commented Aug 3, 2024 • edited Loading

Notes:

github-actions bot commented Aug 4, 2024

freakboy3742 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kattni commented Aug 4, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kattni commented Aug 5, 2024

kattni commented Aug 7, 2024

kattni commented Aug 8, 2024

freakboy3742 commented Aug 9, 2024

freakboy3742 commented Aug 21, 2024

kattni commented Aug 22, 2024

freakboy3742 commented Aug 23, 2024

kattni commented Aug 27, 2024

kattni commented Aug 27, 2024

freakboy3742 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kattni commented Aug 3, 2024 •

edited

Loading