Remove examples folder [main branch] #3913
Conversation
handrews
added
the
examples
| @@ -1821,7 +1821,7 @@ The key value used to identify the callback object is an expression, evaluated a | |||
| ##### Patterned Fields | |||
| Field Pattern | Type | Description | |||
| ---|:---:|--- | |||
| <a name="callbackExpression"></a>{expression} | [Path Item Object](#path-item-object) | A Path Item Object used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available. | |||
| <a name="callbackExpression"></a>{expression} | [Path Item Object](#path-item-object) | A Path Item Object used to define a callback request and expected responses. A [complete example](https://github.com/OAI/learn.openapis.org/tree/main/examples/v3.0/callback-example.yaml) is available. | |||
There was a problem hiding this comment.
I'd prefer to link to wherever we host these examples on the actual learn.openapis.org site. One thing we're trying to do by moving these examples out of this repo is to stop linking into GitHub repos and only treat spec.openapis.org and learn.openapis.org as official published locations. This might require getting them published on the learn site first if they're not on a page and are instead just sitting there right now.
There was a problem hiding this comment.
@handrews Something like this link https://learn.openapis.org/examples/v3.1/tictactoe.yaml? If yes, then it seems that we are lucky since the whole folder is already deployed.
Although I have one question, I understand why we want to point to the website but are we sure that this is currently the best thing we should be doing? I am asking because Github formats the file better than the browser itself.
There was a problem hiding this comment.
Hm... we should add something to the Learn site's build to get them to render as syntax highlighted HTML. I'd rather take the extra time to do that than to move to an interim place, have people get used to that, and then have to convince them to stop looking at the interim place. Particularly because we obviously need to have these in GitHub somewhere. I just think folks should look at the Learn and Spec sites and ideally stop looking at GitHub unless they need to do work in the repository (including filing issues, commenting, etc.).
But I am totally making this plan up as I type it, and others might feel differently.
There was a problem hiding this comment.
With a bit of experimentation, it looks like we could move the JSON and YAML files under _includes and do something like this for each one:
---
layout: default
title: Tic-Tac-Toe Example (YAML)
parent: Examples
nav_order: 1
has_toc: false
---
{% highlight yaml %}
{% include examples/v3.1/tictactoe.yaml %}
{% endhighlight %}
There was a problem hiding this comment.
@Bellangelo we discussed this in the TDC call this morning and agreed that we need the links to go to rendered pages on the Learn site. So please, when you get a chance, if you could add pages there first, and once that is approved we can finish these PRs out here. LMK if you encounter any problems on the Learn site PRs and I'm happy to help.
|
@ralfhandl Did you incorporate these changes into one of your recent PRs? This looks familiar. If yes, can we close this one? |
No, the examples were copied from the OAS repo to the learn repo via OAI/learn.openapis.org#102, and this cleanup is still pending. This PR needs to be adjusted to reflect @handrews comment, which needs OAI/learn.openapis.org#105 to be merged first. And we need two more PRs to adjust 3.0.4.md and 3.1.1.md in the corresponding dev branches: |
Partially closes #3854
We have moved in this OAI/learn.openapis.org#102 the examples to the learn.openapis.org repo. So in this PR we are cleaning the main branch by removing the examples folder and making any related changes.
v3.0.4-dev: #3914
v3.1.1-dev: #3915
v3.2.0-dev: #3916