search

pulumi / docs

All things Pulumi docs!
https://pulumi.com
Apache License 2.0
128 stars 221 forks source link

docs layouts++ tech debt #9320

Open susanev opened 1 year ago

susanev commented 1 year ago

overview

im unfortunately leaving some tech debt around that's not super great, i did improve it quite a lot, but its still not solved. there's no real urgency other than its gonna lead to bugs, so i recommend addressing it the next time there are any major docs changes.

background

so whats the tech debt susan

  1. we do not need the api layout at all, it should be able to use the package layout, but to make this change we will have to make a change in pulumi/pulumi because it relies on the api layout https://github.com/pulumi/pulumi/blob/master/pkg/codegen/docs/templates/index.tmpl#L5
    • to resolve this we need to make sure the api layout is exactly the same as the package layout ship that then ship the change in pulumi/pulumi to change it to package, then delete the api layout
  2. but really we should not need the package layout in registry at all, this should be able to use the list/single layout in docs, so that every single docs page is using the same layout (as it appears visually)
  3. another thing of note is that all the community packages set the layout for their docs pages in their repos, if we remove the need to set a layout at all we wont have this problem at all when we make changes and we will not be dependent on community folks updating their layouts
  4. we really shouldn't need list and single; make 1 layout, then have list and single rely on that 1 layout so there's no repeated layout, and its extremely easy to make changes
  5. the registry list layout should prolly be a partial, then have the docs list/single account for that partial
  6. we should not need two breadcrumb partials, both hugo and registry should be using the same partial for breadcrumbs
  7. i started collapsing all docs css into https://github.com/pulumi/pulumi-hugo/tree/master/themes/default/theme/src/scss/docs but there is still some shared css with marketing; there really should be separation here so folks can make changes without being terrified they are going to break something in marketing

sry i wasn't able to get to this, this week. hope this info is helpful to yall.

susanev commented 1 year ago

cc/ @cnunciato @sean1588 @interurban pls emoji this in someway so i know you saw this, thx folks!

sean1588 commented 1 year ago

thanks @susanev for the detailed description and for outlining all the changes and thanks for all the improvements you made ❤️