docs: update markdown template #571
Conversation
|
Issues linked to changelog: |
|
|
||
| // Remove the ".proto" extension | ||
| extension := filepath.Ext(name) | ||
| title = strcase.ToCamel(name[0 : len(name)-len(extension)]) |
There was a problem hiding this comment.
I noticed in the gloo PR this results in these titles: GatewaySoloIo, EnvoyGlooeSoloIo
Is that what we want?
Perhaps we only want to camelCase names that have no . remaining after stripping the extension?
There was a problem hiding this comment.
tbh, I'm not sure. This is a formatting change, and the request seemed to be focused mainly at our user-facing APIs. I'm leaning towards including them for consistency, rather than trying to come up with a more complex filter for which files this applies to. wdyt?
There was a problem hiding this comment.
I think this is primarily a product and docs question.
However, it's also a question about whether it's a strict improvement compared to the current state, and I'm concerned that while GatewaySoloIo is more aesthetic, it's also more confusing than gateway.solo.io.proto since it doesn't correspond to anything meaningful.
There was a problem hiding this comment.
so I agree with @arianaw66 that in this case the name does not make sense. Only the ones that end in .proto I think should get the name change. the ones that end in .project should not. However, I also think we should not have any of these .project resources in our docs, especially since those are just overview pages with all the CRs. So what we could do is one of the following:
Option 1:
- Not change the name for .project files.
- Display them as-is in the docs.
Option 2:
- Leave the change as-is and remove these references from the docs. We can do this manually on our end if it can't be done in the template or is too hard to implement.
Co-authored-by: Ariana W. <[email protected]>
Co-authored-by: Ariana W. <[email protected]>
There was a problem hiding this comment.
LGTM provided we're okay with Option 1 and re-adding .sk.md in the docs titles for .project files per https://solo-io-corp.slack.com/archives/C03MFATU265/p1732053402150619?thread_ts=1731948029.520829&cid=C03MFATU265
Background
https://github.com/solo-io/solo-projects/issues/6612#issuecomment-2447651284 contains the necessary context behind these changes.
Testing
Testing this locally was difficult, and it was easier to just run code generation in Gloo. I opened #572 to track this gap in local functionality.
I opened solo-io/gloo#10362 to demonstrate how this would impact the generated docs in Gloo