feature: linking doc snippets to our repo #1725
Conversation
franciscolopezsancho
added
the
Documentation
| @@ -55,8 +55,7 @@ Now that we have our Entity state defined along with its events, the remaining s | |||
|
|
|||
| Let's have a look at what our shopping cart entity will look like for the first 2 steps from the above list: | |||
|
|
|||
| [source,java] | |||
| .src/main/java/com/example/shoppingcart/ShoppingCartEntity.java | |||
| https://github.com/lightbend/kalix-jvm-sdk/blob/main/samples/java-spring-eventsourced-shopping-cart/src/main/java/com/example/shoppingcart/ShoppingCartEntity.java[src/main/java/com/example/shoppingcart/ShoppingCartEntity.java] | |||
There was a problem hiding this comment.
this is a good idea, IMO
but we need to preserve
[source,java]
.
This is need for the syntax highlight on the included snippet.
The . needs to be just before the line. This is to apply a special style to the line showing the file name.
There was a problem hiding this comment.
Ok. I'll go ahead then.
This is how it would look
There was a problem hiding this comment.
Should rather look like this if syntax highlight is added.
There was a problem hiding this comment.
Would be neat if it could be a little bit more automatic than providing full paths everywhere, like links we do in paradox where the repo url is listed once and given a name that can be linked to with @extref.
There was a problem hiding this comment.
We can use some asciidoc variables, but that won't be fully automatic.
The problem is that we need to split the line in three as well:
- https://github.com/lightbend/kalix-jvm-sdk/blob/main/
- samples/java-spring-eventsourced-shopping-cart/
- src/main/java/com/example/shoppingcart/ShoppingCartEntity.java
(1) can be on a variable, (2) is a specific path that we don't want to render on the page and (3) is what we want to render.
There was a problem hiding this comment.
Was looking at docs today and this crossed my mind.. I'm not really sure if hiding the samples/java-spring-eventsourced-shopping-cart/ is too big of an advantage.. I understand that approach when we, in the context of a page, are always using examples from the same repo and that is clearly mentioned somewhere.. because then it's obvious that is a relative path inside the mentioned codebase. But in our docs, it's not always clear what repo is associated with the context and having the sample there would help to contextualize I think. And that could make it easier to automate the process I suppose.
|
Rich will soon migrate the Kalix theme to the current Antora version. After migrating we can ask for assistance with better support for this linking. |
|
closing this here and keeping an issue #2184 instead. |
I think this might be useful to see the source code when in doubt or curious. I found myself going to the source code.
If we agree I'm happy to do the rest.