feat(docs): enrich documents with metadata #457
Conversation
Transactions CostsSizes and execution budgets for Hydra protocol transactions. Note that unlisted parameters are currently using
Cost of Init Transaction
Cost of Commit TransactionCurrently only one UTxO per commit allowed (this is about to change soon)
Cost of CollectCom Transaction
Cost of Close Transaction
Cost of Contest Transaction
Cost of Abort Transaction
Cost of FanOut TransactionInvolves spending head output and burning head tokens. Uses ada-only UTxO for better comparability.
|
|
From |
| ```mdx-code-block | ||
| <DocumentMetadata | ||
| lastUpdatedAt="{{last-updated-at}}" | ||
| authorInfo="{{author-info}}" |
There was a problem hiding this comment.
no real good answer for this.
removing 🏃
| * | ||
| * This source code is licensed under the MIT license found in the | ||
| * LICENSE file in the root directory of this source tree. | ||
| */ |
There was a problem hiding this comment.
Don't give your code to Facebook 🙃
| * | ||
| * This source code is licensed under the MIT license found in the | ||
| * LICENSE file in the root directory of this source tree. | ||
| */ |
| }: Props): JSX.Element { | ||
| return ( | ||
| <div className={styles.block}> | ||
| <i className={styles.info}>Last updated at: <b>{lastUpdatedAt}</b></i> |
There was a problem hiding this comment.
What about we make those:
- Links to the actual commit (visualized on Github)
- Relative times (e.g. 3 days ago)
There was a problem hiding this comment.
New looking style
wdyt?
There was a problem hiding this comment.
What about not showing the date at all, and making the '2 minutes ago' the link 😅? We should have done that while pairing I guess, this back and forth feels unproductive. Requirements unclear. Sorry.
There was a problem hiding this comment.
Other than that, I think it's amazing :D
ffakenz
force-pushed
the
feat/gh-pages/docs-custom-template/456
branch
4 times, most recently
from
be9be14 to
7ac068b
Compare
ffakenz
changed the title
ffakenz
changed the title
ffakenz
changed the title
ffakenz
changed the title
ffakenz
changed the title
ffakenz
changed the title
docs/scripts/document-metadata.sh
Outdated
| sed -i "s/$PLACEHOLDER/$REPLACEMENT/g" $MD | ||
|
|
||
| PLACEHOLDER="{{last-translated-at}}" | ||
| REPLACEMENT=$(git --no-pager log -1 --pretty=format:'%ad' --date=local docs/i18n) |
There was a problem hiding this comment.
Seeing this now, this is a bit more complicated actually 🤔
This will yield the date where any translation was written. But we want that to be specific to that page.
Which makes me wonder for a minute: we have possibly many translations per page (fr, jp, ...). So we have 2 options I believe:
-
- Indicate when each translation was last translated. On the one hand, this is handy to see which translation are lagging behind from the reference source. Yet on the other hand, it can become cumbersome / noisy once we start adding more languages.
-
- Instead of indicating the
last-translated-aton the reference source (i.e.en), we instead put a warning on each translated page if the source was modified AFTER the translation. Something a bit visible that gives readers a clear warning "This translation may not be up-to-date, the source was changed X days ago!".
- Instead of indicating the
I think option (2) is also easier to handle / implement with that bash script approach, as we can simply leave last-translated-at blank for files outsides of i18n and, for thos in i18n, look for the original under the same path and indicates both date to the component. And in the component, either:
- display only the "last updated at" relative time; or
- display the "last updated at" relative time AND a warning if it is before the "last updated at" of the source.
There was a problem hiding this comment.
New looking style for i18n
Normal pages looks the same but they don't have "last translated at" info
wdyt?
ffakenz
force-pushed
the
feat/gh-pages/docs-custom-template/456
branch
from
7ac068b to
0c4260f
Compare
There was a problem hiding this comment.
The metadata format is suboptimal and some things can be made simpler by arranging the data slightly different in a hierarchical way + avoiding redundancy in the data structure. Furthermore, working with dates and displaying things can be made simpler using a time library like momentjs.
But, done is better than perfect.. so I can approve if you don't want to look into my suggestions.
docs/.gitignore
Outdated
| @@ -7,6 +7,7 @@ | |||
| # Generated files | |||
| .docusaurus | |||
| .cache-loader | |||
| /static/metadatas.json | |||
There was a problem hiding this comment.
Data is already plural. So there is no such think like datas.
There was a problem hiding this comment.
True.
I wanted to distinguish (in code) a single document metadata from the full set in code.
Any suggestions for renaming?
is "documents-metadata" a better fit?
There was a problem hiding this comment.
renamed to docs-metadata.json
hope this is a better fit.
| ``` | ||
|
|
||
| ```mdx-code-block | ||
| <DocumentMetadata /> |
There was a problem hiding this comment.
I assume you have considered this, but can't hurt to ask: Do we have a global template or so to not need to repeat this for each page?
There was a problem hiding this comment.
Indeed I consider it but haven't started to work on that just yet but I think it's the right way to move forward.
Any suggestion on the approach?
There was a problem hiding this comment.
I have not found any way to achieve this by using docusaurus or any plugin.
Do you have any alternative?
docs/scripts/document-metadata.sh
Outdated
| @@ -0,0 +1,5 @@ | |||
| #!/usr/bin/env bash | |||
There was a problem hiding this comment.
I don't see this file used anywhere. Was this an earlier approach?
There was a problem hiding this comment.
yes, It was part of an earlier approach.
but it is also part of current approach to tackle the site-matadata.
still working to improving this approach, any suggestion?
There was a problem hiding this comment.
yes, It was part of an earlier approach.
but it is also part of current approach to tackle the site-matadata.
still working to improving this approach, any suggestion?
|
|
||
| async function main() { | ||
|
|
||
| Utils.getItems("**/*.md", { "ignore": ['**/node_modules/**'] }) |
There was a problem hiding this comment.
Why the Utils. prefix on these local functions?
There was a problem hiding this comment.
Extracting all behaviors to this Utils object makes the main function more readable, imo.
What do you think would be a better approach?
| .replace('/current/', '/') | ||
| .replace('/index', '') | ||
|
|
||
| // @TODO rename to docusaurus-plugin-content-docs-docs |
There was a problem hiding this comment.
Can we address this TODO (not sure exactly what it says)?
There was a problem hiding this comment.
if we rename the directory of docusaurus-plugin-content-docs to docusaurus-plugin-content-docs-docs then this if/else can be removed.
do u agree we should move on with this?
| lastUpdatedAt, | ||
| relativeTimeSince, | ||
| commitHash | ||
| } |
There was a problem hiding this comment.
Instead of storing the metadata for the source and its translations next to each other, it would be much easier to process (and not need to enumerate known languages later) if we store it in a hierarchy.
For example, instead of:
"docs/getting-started": {
"lastUpdatedAt": "Fri Mar 18 18:40:15 2022",
"relativeTimeSince": "5 months ago",
"commitHash": "c81338744"
},
"fr/docs/getting-started": {
"lastUpdatedAt": "Sat May 21 09:28:11 2022",
"relativeTimeSince": "3 months ago",
"commitHash": "7ebee872d"
},
"ja/docs/getting-started": {
"lastUpdatedAt": "Thu Jul 7 15:33:21 2022",
"relativeTimeSince": "6 weeks ago",
"commitHash": "ff12ae270"
},
This format:
"docs/getting-started": {
"source": {
"lastUpdatedAt": "Fri Mar 18 18:40:15 2022",
"relativeTimeSince": "5 months ago",
"commitHash": "c81338744"
},
"fr": {
"lastUpdatedAt": "Sat May 21 09:28:11 2022",
"relativeTimeSince": "3 months ago",
"commitHash": "7ebee872d"
},
"ja": {
"lastUpdatedAt": "Thu Jul 7 15:33:21 2022",
"relativeTimeSince": "6 weeks ago",
"commitHash": "ff12ae270"
},
There was a problem hiding this comment.
More comments on the metadata format:
-
lastUpdatedAtandrelateiveTimeSinceare quite redundant and the latter tends to go out of date. No need to store it, but compute it when rendering using one of the many javascript libraries (e.g. https://momentjs.com/) -
The time format of
lastUpdatedAtseems to be localized and I would suggest to use a more canonical format like ISO 8601. You can get that usually quite easy with just another flag. -
We should store the full hash in
commitHashas the truncated version can theoretically collide (more easily).
| Last commit hash: <a href={link}><b>{commitHash}</b></a> | ||
| </i> | ||
| , renderLastTranslatedAt: (documentPath: string, lastTranslatedAt: string) => { | ||
| const languages = ['fr', 'ja'] //@TODO move to config |
There was a problem hiding this comment.
See comment above. Grouping languages per page on collecting metadata will not require any configuration.
| ) ? obj : acc | ||
| }) | ||
| } | ||
| } |
There was a problem hiding this comment.
Using a library like momentjs this whole code here would be quite simple. For example
`${moment(translationChangedAt).from(sourceChangedAt, true)} behind source`
would give you a relative time to the source like "3 days behind source".
ffakenz
force-pushed
the
feat/gh-pages/docs-custom-template/456
branch
from
3f67b6e to
3118289
Compare
|
When trying to build the doc I got this failure: Any clues? |
Seems like the |
Add author, updateAt, and translateAt via templating to markdown pages. The idea is to add these templates to all of the relevant markdown documentation pages, so that upon running the script during the CI step the Github Page is enriched with the commit information.
|
@abailly-iohk nice recommendation. |
Also reformat file automatically using newly installed prettier, seems default layout is not great...
Also reformat file automatically using newly installed prettier, seems default layout is not great...
We introduced a wrapper over EditThisPage by running this command: ```sh yarn run swizzle @docusaurus/theme-classic EditThisPage -- --wrap ``` Now the wrapper imports the component and voila, its available everywhere
They are very hard to link the document url and file paths.
We had to do a hack in order to map the document file-path to the document url-path, but this unlocks the possibility to use the component inside BlogPostItem wrapper
ch1bo
force-pushed
the
feat/gh-pages/docs-custom-template/456
branch
from
6fa7684 to
bec4e97
Compare
Fixes #456