Get docusaurus building #1434
Get docusaurus building #1434
Conversation
|
I think moving docs/ into website/ might be a step too far... but I'll leave @kriswest to think about that |
There was a problem hiding this comment.
I see an issue in the schema handling: docs pages when generated should point to the 'next' version of schemas. Then the versioning scripts should generate copies of those pages, copies of the schemas and update links from one to the other so we get frozen versions of both associated with each other.
See all the package.json scripts that start with version - I think the paths are all still correct as I think those all operate off the website/static folder paths... However, the copy-schemas and copy-appd scripts definitely now have incorrect paths in them. This page: https://fdc3.finos.org/schemas/next/app-directory.html may be broken in your version... Try deleting this file: https://github.com/InteropIO/FDC3/blob/monorepo-docusaurus/website/static/schemas/next/appd.schema.json
then build and if the file doesn't get replaced its broken.
For testing context schemas try the schema link any page in the next version - but watch out for URL hardcoded to their production values, you'll need to sub-in the local or preview origin. Same goes for API schemas in the new 'specs' pages.
It'd also be helpful to have a quick word in teh PR description on why moving docs into the website folder helps (I do know its the normal pattern for a docusaurus site). The license covering said docs (the CSL) remains in the root directory. 'The Standard' is essentially the docs and schema files - the schema files now reside in /packages/fdc3-schema and /packages/fdc3-context and appear to be under the Apache-2.0 license (as thats whats in their package.json files).
@robmoffat I don't actually know the licensing implications here. The schemas contain information that is not in the docs and need to be a formally under the CSL, as do the docs. If this is problematic, it is so in both cases - perhaps worse in the schema packages as they explicitly state a different license...
website/schema2Markdown.js
Outdated
| @@ -350,11 +350,15 @@ function retrieveTitleFromSchemaData(schemaData, pathInSchema) { | |||
| } | |||
|
|
|||
| function parseSchemaFolder(schemaFolderName) { | |||
| const schemaFolder = `./static/schemas/2.1/${schemaFolderName}`; | |||
There was a problem hiding this comment.
hardcoding 2.1 into the generated schema paths. Needs to be 'next' instead. The versioned schemas are locked and don't change. Those in 'next' can change with a PR then get locked down when we run the versioning script when preparing a final release.
There was a problem hiding this comment.
There's a function looking to scan for the folder name "context". That folder only exists within the folder 2.1. I can't change this to "next", because then the rest of the function breaks, because the files related to context don't exist in the "next" folder.
Should the "next" folder be updated? Should we handle the fact that some of the schemas folder don't have *.schema.json files? Please advise.
There was a problem hiding this comment.
The folder doesn't exist in the /website/static/schemas/next folder as this script was broken:
The second path needs to change, probably to:
"copy-schemas": "del-cli static/schemas/next/*/ && cpy \"../packages/fdc3-schema/schemas**\" static/schemas/next/ && cpy \"../packages/fdc3-context/schemas**\" static/schemas/next/",
(and its now two different copies to do as the schemas folder got split into two different packages)
The copy-appd script also probably needs to change to catch that schema file:
"copy-appd": "cpy \"../packages/fdc3-standard/src/app-directory/specification/*.schema.json\" \"static/schemas/next/\"",
| @@ -14,7 +14,7 @@ Accepts an optional `app` parameter in order to specify a specific app. | |||
|
|
|||
| ## Schema | |||
|
|
|||
| <https://fdc3.finos.org/schemas/next/context/action.schema.json> ([github](https://github.com/finos/FDC3/tree/main/schemas/context/action.schema.json)) | |||
| <https://fdc3.finos.org/schemas/2.1/context/action.schema.json> ([github](static/schemas/2.1/context/action.schema.json)) | |||
There was a problem hiding this comment.
This shouldn't have changed. The links should point to next in the unversioned docs or it'll point to the existing version's schema.
Docusaurus is pretty opinionated on where the docs files should live. There were a bunch of build errors that just disappeared once I moved the files into the folder docusaurus likes them to be in. If you want the docs folder to stay separate, I assume that you can, but there's going to be a lot of juggling on someone's part. |
Hmm, thats odd as AFAIK we aren't getting build errors in the pre-refactor version with docs up a level and the docusaurus config pointing at them. Got any details on the errors (out of interest)? Or any details on the juggling needed if we don't do it? |
|
Oh and we've got this PR hanging out there as part of the Citi Hackathon, which is trying to upgrade existing docs to work in Docusaurus 3: #1418 I'd guess we'll have to make some similar changes for anything introduced since then. I can ask them to rebase on main as the fdc3 for web docs just got merged in. |
|
I've updated the copy/paste scripts to move the schemas from the correct place. |
Thanks @julianna-ciq, don't forget to run schema2markdown again, it should drop a bunch of the context docs pages from the diff (currently 217 files) by eliminating the change to the schema URL. I'm seeing some additional differences in the context docs pages that are reverting recent changes, e.g. instrumentList losing its id and name properties: Those should vanish as well, thats probably a result of generating from the 2.1 schemas instead of next 🤞 |
No description provided.