Closed garlick closed 1 year ago
vsoch
commented
1 year ago Thank you for turning this into an issue! (I was going to suggest the same!) I think if we can get some other voices into the discussion, if there is desire for a bit of rebranding of the docs, I can definitely make time for it soon.
Update: and here is my main issue with the default sphinx readthedocs: https://github.com/flux-framework/rfc/pull/358#issuecomment-1352561810
grondo
commented
1 year ago It would be great to brand the docs. I think the only reason we haven't is that nobody has had the time and some unbranded docs is better than no docs at all.
vsoch
commented
1 year ago I can doooo it! I always have time. :t-rex: I'm just interested to know what style(s) out there on the wild internet people like?
springme
commented
1 year ago Yes, it’s great to spend time on the brand and the documentation. Please include Ryan and Jane in the discussion. Jane and Holly have worked on documentation for the WEG group. It doesn’t all have to look the same but we should try to at least coordinate so users have a similar experience or at least pointers to documentation from the same places.
Thanks for working on this.
Becky
vsoch
commented
1 year ago Ping @xorJane and @hauten ! And I couldn't find Ryan on GitHub could someone ping him to the thread here? I think if I remember some of the WEG group docs also used Mkdocs - and the ones I linked above are similar, but Mkdocs Material (link to template) and we get that working with sphinx via Sphinx material and I've recently also seen Sphinx Immaterial.
The benefit of sphinx (I think) is that it's really good for having multiple versions of things, and of course works out of the box on readthedocs, and can support rst or markdown. I think mkdocs by itself might have plugins you can add for versioning, but it would be a larger set of work to port the current restructured syntax to markdown see. So my suggestion is some variant of sphinx-material so it looks like the other docs, but is easy to port the current .rst docs to.
And for the main flux portal we can really do anything - I like the one I linked above https://software.llnl.gov/radiuss/projects/ because I added automation to get updated data about the repos nightly, so the reader always sees the latest stars, logo, languages, etc. Adding a new project is just writing it into a line of a yaml file. There are likely other stats we could show for a smaller set of projects.
grondo
commented
1 year ago Sounds great! We have an issue with the current "portal" (flux-framework.github.io repo) because it requires a manual update to add a NEWS item for new releases. Automating that would be huge.
I'm just interested to know what style(s) out there on the wild internet people like?
My opinion is that the branding should start with our existing logo and its color scheme. I don't have much input beyond that - I kind of like the clean design of the default RTD theme, though I'd prefer a darker scheme. The nice thing about readthedocs is that many users of documentation are used to the interface and layout and if you are looking for documentation, you're likely not looking for excessive branding and a unique layout that gets in the way of reading text.
grondo
commented
1 year ago cc: @ryanday36
vsoch
commented
1 year ago Sounds great! We have an issue with the current "portal" (flux-framework.github.io repo) because it requires a manual update to add a NEWS item for new releases. Automating that would be huge.
I can totally do that! We can make a GitHub action under RADIUSS so other projects can easily do it too. Ping @davidbeckingsale OK with you?
davidbeckingsale
commented
1 year ago Sounds great! We have an issue with the current "portal" (flux-framework.github.io repo) because it requires a manual update to add a NEWS item for new releases. Automating that would be huge.
I can totally do that! We can make a GitHub action under RADIUSS so other projects can easily do it too. Ping @davidbeckingsale OK with you?
Yes, sounds great!
hauten
commented
1 year ago Flux logo file & the two primary colors attached
hauten
commented
1 year ago No one mentioned this, but if desired, it's easy to embed the Twitter feed. Ex: https://github.com/LLNL/llnl.github.io/blob/main/_layouts/news.html
vsoch
commented
1 year ago yeah! I've done that before - the only issue with that is that it doesn't work on all browsers, or if some people block particular scripts. As an example, here is my podcast site with an embedded feed in firefox:
(note the white space on the right)
and then in chrome:
so if we add that, we just have to account that (probably a good percentage) of folks won't see it.
And I promise I will match colors! I have gimp (not as great as photoshop) and can do that. I think likely for the new portal, however, my preference is for simplicity so it would be mostly white (with an option for a dark theme) and just the logo (already correctly colored) front an center!
I'm working on the docs action now!
cmoussa1
commented
1 year ago And I promise I will match colors! I have gimp (not as great as photoshop) and can do that. I think likely for the new portal, however, my preference is for simplicity so it would be mostly white (with an option for a dark theme) and just the logo (already correctly colored) front an center!
@vsoch I know I am late to the party (lots of great discussion above), but I just wanted to mention that I love that you plan to include an option for a dark theme! I think it's such a useful option, especially as the day goes on and my eyes get tired. 😅
I would agree with @grondo that a simpler theme that aligns with our current color scheme might be best for our documentation too. I think it would look great both in light/dark mode. Keeping things simple and easy to navigate is IMHO the way to go with our site, especially with our multiple projects. :-)
vsoch
commented
1 year ago @cmoussa1 oh it's sort of becoming essential for me these days - the more I use dark themes the more I hiss like a vampire when I see a completely white page! :vampire:
I had a few hours pair programming so I had to pause on the action but I'm going back to it now.
vsoch
commented
1 year ago Okay an update! This took longer than I anticipated because I couldn't just grab the body - Flux release notes point to a NEWS.md that has all the releases so I had to first parse that URL, retrieve, and then cut at the correct release! But I was able to finish the prototype, and you can see the PR here: https://github.com/flux-framework/flux-framework.github.io/pull/54. Please click the links in the description and take a look at the example output (the files we would generate) e.g., here are the non-expanded sections:
And when you cli
ck the arrow next to the star it expands out to show the markdown generated:
Mostly everything is customizable, and see the table of options here for the action: https://github.com/rse-ops/release-actions/tree/main/docs#github-action
My suggested next steps:
And I can of course be on call if anything goes wrong after that to debug, etc. After this automation is in, I have an idea for refactoring the portal so I'll start working on that next.
vsoch
commented
1 year ago hey everyone! Another update! The action is working well https://github.com/rse-ops/release-actions/ and is now added to the flux framework repository, where it added 19 releases from 2022! I've updated the issue to have some action items - the next of which is to work on the interface itself. I'm going to do some work right now on the Flux Operator / RESTful API but I will definitely (likely) get to this UI refactor this weekend. Have a good one y'all and thanks for the discussion above - excited to work on this and share what I come up with for feedback! :partying_face:
Also as a sidenote - I was chatting with @davidbeckingsale and we were talking about other release tasks that would be nice to automate - if you have an idea/request please open an issue here: https://github.com/rse-ops/release-actions/issues I made the action repo general to "release-actions" anticipating we might want more.
vsoch
commented
1 year ago New portal is ready for review :point_right: https://github.com/flux-framework/flux-framework.github.io/pull/60
vsoch
commented
1 year ago @hauten @xorJane take a look! https://flux-framework.org/ I'm not a web designer so please be critical, and it would be super fun if you want to contribute directly (@hauten you must be really busy but it's always really fun doing PRs with you!)
We can work on a docs theme next! Should I start from the rst here or is there a smaller rst docs base that would be better?
vsoch
commented
1 year ago okay last action item for the portal - dark mode! https://github.com/flux-framework/flux-framework.github.io/pull/68 I really struggled with the position of the slider - When I put it in the navbar no matter what I did I couldn't get it to move down ever so slightly (and look visually correct). I think my preference would be for it to be there, but not hugging the top of the page. @hauten I suspect you have good css chops if you want to take a look! This is the first time I've implemented a dark mode from scratch and it was kind of neat - the trick is to have variables in your .css styling, and then have them link to a data-theme that corresponds to each of the styles (and then have that save in the local storage so a user preference is saved).
@garlick I think the current action items for this particular set of work will be done after this dark mode is added, and my question for you is how you would like to proceed with testing refactor for the readthedocs themed pages? I have in mind a mkdocs theme (also with sphinx) that matches some of the current lab sites and the current flux restful api and operator. What I want to ask you is if 1. you are interested in seeing what this would look like, and 2. what repo I should test on (is this flux-docs one the right one?)
hauten
commented
1 year ago I'm clearing some things off my plate so I can catch up to this!
vsoch
commented
1 year ago Dark mode is live! https://flux-framework.org/ Thanks @hauten for making it chef's kiss !
I'd like to do some work on the main docs theme, but I'll wait until you are back @garlick and @grondo to point me to which repo / readthedocs markdown as a good start. Happy holidays everyone! :snowman:
vsoch
commented
1 year ago As promised - here is the first proposal for updating the docs with mkdocs sphinx! I've also put there a list of next steps I'd like to do (if these changes are accepted) https://github.com/flux-framework/flux-docs/pull/183
Updated with Action items
[snip] Also, has there been feedback about the style of the docs? I personally find the default readthedocs template hard to move around, or kind of depressing if/when I see it that nobody changed anything. One thing I wanted to bring up for discussion is that maybe part of users being better able to find things and better enjoy / contribute to the docs overall would be to reformat into a nicer template? Here are some randoms that I've done that all use sphinx (and I even use markdown for a few for easier user contribution!)
I think we have an opportunity moving forward to really make the docs shine, and part of that, although it's not "cool work" is branding. E.g., this page https://flux-framework.org/ to any trained eye is a GitHub pages theme called Cayman https://pages-themes.github.io/cayman/ with maybe a color changed. And I'm not saying we have to go this route, but now we have two flux associated projects with these docs:
If the team wants to chat about these ideas, and if there is a desire to have a nice, unified portal for flux projects (e.g., akin to https://software.llnl.gov/radiuss/projects/ but for fewer projects and rebranded for flux) and then more unified branding of the individual project docs, I could probably help. It will make a difference, I think, when new users are trying it out and forming impressions, and/or finding/not finding stuff easily (re: the email earlier today). Let me know what you think!
Originally posted by @vsoch in https://github.com/flux-framework/rfc/issues/358#issuecomment-1352558195