jenkins.io
jenkins.io copied to clipboard
jenkins-infra
Add simple left side navigation list to dev docs to improve layout
Add simple left side navigation list to dev docs to improve layout, as the first of a series of PRs to follow for Issue #4718.
Currently, visually the new dev docs layout looks like the following:
I will probably need more time to get familiar with the codebase as well as how asciidoc works before I submit more PRs incrementally for participating in hacktoberfest this year.
Hey @krisstern this looks great! I was checking out the deploy link to see how the navigation works. I like the idea a lot, but the concern I have at this moment would be the navigation changes depending on the link you go to. If the plugin tutorial or Jenkins developer reference links, this navigation remains. However, if you select any of the other links, the navigation goes away and the previous navigation is used. It's a bit inconsistent, but understand that this is a challenge, and all of the work you've done thus far is fantastic. Let me know if you have any questions!
Thanks @kmartens27 for the reply! Yes, I agree with you this PR as it stands is incomplete. Let me add more code to make the navigation consistent. But I do have some questions to ask regarding the codebase though which I will need some time to compile. I will get back to you shortly.
No worries at all @krisstern ! I'll be honest, I am not as knowledgeable in the code base of Jenkins, as most of my focus is on the documentation. However, I'm more than happy to help figure out who we can ask about it and get some guidance!
@kmartens27 Do you happen to know what is the equivalent line in https://github.com/jenkins-infra/jenkins.io/blob/master/content/_layouts/documentation.html.haml#L7 where it where it says:
site.pages.reverse_each do |page|
This works for the User Handbook, but not for the Dev Docs.
Hey @krisstern I do not know that one unfortunately, I have reached out to some peers to see if they might have the insight we're looking for, and shared the PR so I'm hoping that someone will be able to help us out on this one.
This works for the User Handbook, but not for the Dev Docs.
This code iterates over all pages, collecting those that are tutorials. WDYM when you write it doesn't work? What are you trying to accomplish?
I have just added the TOC to all pages within the Dev Docs. See if this version is better and do let me know if some styling needs to be included in this PR. Cheers!
This works for the User Handbook, but not for the Dev Docs.
This code iterates over all pages, collecting those that are tutorials. WDYM when you write it doesn't work? What are you trying to accomplish?
Hi @daniel-beck I am trying to iterate through the Dev Doc pages but don't know the equivalent to do it programmatically, so the TOC does not "expand and collapse" (in Mark's words) now, since it is only hard-coded at the moment.
Just polished up the PR to make the CSS styling for the Dev Docs more consistent.
To clarify, is the problem that the index page, the plugin tutorial, and the reference index page have the same sidebar, while the extensions index has none, and the improve plugin tutorial and the how-to guides index has the expanded developer reference sidebar?
Not anymore, I have added the same Dev Docs sidebar menu to all sections including the index page, the plugin tutorial, the reference index page, the extensions index, the improve plugin tutorial, as well as the how-to guides in the latest version/last commit.
I am attaching here the screenshots for the different sections here for reference:
I am attaching here the screenshots for the different sections here for reference:
Ah, interesting. I was checking the preview site deployment, and it hasn't been updated with this change yet.
Ah, interesting. I was checking the preview site deployment, and it hasn't been updated with this change yet.
Yeah, I have been waiting for hours for the latest preview version to come out but that is not available yet. Personally I feel that the latest version is more appealling visually compared to my previous attempts.
Personally I feel that the latest version is more appealling visually compared to my previous attempts.
Absolutely, that ties the different kinds of developer documentation nicely together.
Here's a suggestion:
- Remove the "reference documentation" sidebar items from how-to guides and improve plugin tutorial.
- Add the "reference documentation" sidebar to the reference documentation page and replace its content with an introductory blurb
- Implement the new top-level menu as a partial to minimize copy & paste (while not computing it, like the list of tutorials in the regular handbook).
I have done the first two items as suggested, but ran into some issue while trying to implement the Dev Docs TOC as a partial. Turns out if I use a partial instead the active page item on the TOC will not get highlighted during navigation, so I have abandoned that idea.
The blurb used to replace the Jenkins Developer Reference is as follows:
The Jenkins Developer Reference serves as a resource for all serious Jenkins users and developers alike to have one central place where they can look up and refer to for reliable and accurate information related to Jenkins development overall. While this Developer Reference is by no means completely exhaustive, we welcome any contributions to improve and enhance this document, so that everyone who uses it will benefit much.
For more information regarding the relevant reference topic you may be interested in, please refer to the table of contents located on the left-hand side.
Hi, I am not sure why the preview is not working now, so I am attaching the screenshots for the latest version as captured for my local build:
I just realized there are more in the Jenkins Developers Reference subsections for me to work on, let me finish these as well.
I have just updated the sections and subsections side navbar for the entire Jenkins Developer Reference as well.
@daniel-beck Regarding the earlier suggestion
Remove the "reference documentation" sidebar items from how-to guides and improve plugin tutorial.
I had to walk back on the change to the "Improve a Plugin Tutorial" because in order to make everything consistent, as it is also under Jenkins Developer Reference, the Developer Reference part of the navbar should also be there. Unless we are to permanently remove it from the Jenkins Developer Reference. Let me know what you think.
@kmartens27 We just found out the on-hold label is blocking the preview from building new ones. If we could remove it later then we can maybe see the new previews. Could we please remove this label?
sorry about that @krisstern I wasn't aware it would block things in such a way. That's good to know and I'll be sure to apply it properly from now on.
@kmartens27 Oh no worries, I wasn't aware of that side effect myself as well
Hi all, I was able to come up with a collapsible navigation on the left-hand side today and have rearranged the items a bit (plus added some CSS styling to make the layout more consistent aesthetically). Hopefully this would be more to your liking.
The PR is now ready for another review. A preview screenshot of the look and feel is as attached.
@kmartens27 Would that be possible to get a review in time for Hactoberfest so I can move on to other PRs? This is my first and only so far. Would really want to be able to have 4 PRs completed before the end of October.
Hi @krisstern thanks for the update and all of the work put in on this! I think it looks good from a navigation point, but we would need to get approval from a security perspective. Once it's verified and confirmed in that regard, either myself or one of the copy editors will be able to merge the request.
Aside from that, the only thing that I noticed was a tiny bit of inconsistency between the navigation everywhere else and https://www.jenkins.io/doc/developer/extensions/
The font is thinner/smaller here, but outside of that, I like the navigation a lot!
@daniel-beck when you have a moment would you be able to lend an eye & your expertise?
There seems to be some issue with the navigation for the Extensions Index page in the preview, which I had not been able to reproduce locally previously, hence the latest commit. Not sure exactly why it was working on my laptop but not in the preview before. Hopefully this time I have gotten the issue fixed.