-
Notifications
You must be signed in to change notification settings - Fork 2.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Automate datasource docs for sourceUrl, releaseTimestamp #28948
Comments
Is this close to the expected design for the new fields? I feel like the notes should be highlighted in some manner but can decide how? I am thiking of putting them inside Any suggestions @HonkingGoose ? |
Review of first draftThank you for the first draft of the design! Unfortunately it feels too much like a wall of text to me. Layout problem not your faultThis is not your fault, as we have the same design problem in the current datasource docs. Because we have less fields in the current datasource docs, I did not see the problem before. 🙈 Example of current layout styleFor example, here's the "code" for the AWS Machine Image Datasource, in Markdown: # AWS Machine Image Datasource
**Identifier:** `aws-machine-image`
**Default versioning:** `aws-machine-image`
**Custom registry support:**
:heavy_check_mark: Custom registries are supported.
**Description:**
Rest of docs goes here. We're using bold text as "headings". When there are four items, that works okay-ish. But now that you're adding more information in the Directions to tryTry both of these, and see which we like best:
In any case, we should use real proper headings instead of bold text. Example of proper headings# AWS Machine Image Datasource
## Identifier
`aws-machine-image`
## Default versioning
`aws-machine-image`
## Custom registry support
Yes, custom registries are supported. // Note: I replaced the checkbox emoji with plain text
## Description
Rest of docs goes here. Example of table layout# AWS Machine Image Datasource
## Table of values
| Name | Value | Notes |
| ----------------------- | ------------------- | ----- |
| Identifier | `aws-machine-image` | |
| Default versioning | `aws-machine-image` | |
| Custom registry support | Yes | | // Note: I replaced the checkbox emoji with plain text
## Description
Rest of docs goes here. Alternative table-layout with separate notes headingsIf we are likely to need more than a single sentence as a note, we could try this layout: # AWS Machine Image Datasource
## Table of values
| Name | Value |
| ----------------------- | ------------------- |
| Identifier | `aws-machine-image` |
| Default versioning | `aws-machine-image` |
| Custom registry support | Yes | // Note: I replaced the checkbox emoji with plain text
### Notes about table items
#### Note about table item 1
Note for table item 1.
Another sentence about table item 1.
Final sentence about table item 1.
#### Note about table item 2
Note for table item 2.
Another sentence about table item 2.
Final sentence about table item 2.
#### Note about table item 3
Note for table item 3.
Another sentence about table item 3.
Final sentence about table item 3.
## Description
Rest of docs goes here. Personal preferenceI'm leaning towards the "proper headings and table layout, if we have short notes. |
I like the table with the notes in the table best. The table with notes separate works also, but it takes up more space. And having a table with two columns feels a bit weird. |
While I am at it, I will also change the versioing docs to use proper headings. Since the changes are small, it's better to do it under this issue, rather than a separate PR/issue. |
Describe the proposed change(s).
Blocked by #28947
Once it is completed, we should automatically populate this information into datasource docs pages like https://docs.renovatebot.com/modules/datasource/cdnjs/
The text was updated successfully, but these errors were encountered: