js-ceramic
js-ceramic copied to clipboard
chore: Scaffolding for js-ceramic docs website
New Docs Website
As long-term we want to have similarly maintained and structured docs for js-ceramic as we're currently preparing for js-composedb and js-did, we're adding here a simple Docusaurus docs webpage with a structure similar to what we currently hae for js-composedb.
How Has This Been Tested?
- [X] The docs build and run locally
PR checklist
Before submitting this PR, please make sure:
- [X] I have tagged the relevant reviewers and interested parties
- [X] I have updated the READMEs of affected packages
NET-1701 Setup and write the first version of docusaurus docs for js-ceramic
Description
Spec: https://www.notion.so/threebox/2022-docs-organization-8d19199768944e88bbd390ee4a6aa9eb
We should use the env setup doc created by @alex and also sync with @stephanie to see, if we have any materials on how to setup and run CAS locally.
Note, I changed the PR title since that's what becomes the git commit message, we don't want references to linear tickets in commit messages since linear isn't public but the git commits are
What's the expected role of this docusaurus site compared to our main developers.ceramic.network
docs site and our autogenerated API docs?
What's the expected role of this docusaurus site compared to our main developers.ceramic.network docs site and our autogenerated API docs?
Over time the goal is that:
-
developers.ceramic.network
- developer portal maintained by adoption squad- Will no longer contain any API or autogenerated docs
- Points to specific doc sites below when needed
- js-ceramic docusaurus - maintained by NET squad
- js-did docusaurus - maintained by APPS squad
- js-composedb docusaurus - maintained by APPS squad
What's the expected role of this docusaurus site compared to our main developers.ceramic.network docs site and our autogenerated API docs?
Over time the goal is that:
developers.ceramic.network
- developer portal maintained by adoption squad
- Will no longer contain any API or autogenerated docs
- Points to specific doc sites below when needed
js-ceramic docusaurus - maintained by NET squad
js-did docusaurus - maintained by APPS squad
js-composedb docusaurus - maintained by APPS squad
This is helpful, thanks. I guess my remaining question is does the docusaurus docs within js-ceramic contain just the auto-generated API docs? Or both auto-generated API docs AND manually written documentation about js-ceramic?
This is helpful, thanks. I guess my remaining question is does the docusaurus docs within js-ceramic contain just the auto-generated API docs? Or both auto-generated API docs AND manually written documentation about js-ceramic?
The idea is that it would contain the auto-generated API docs and manually written docs on how to use js-ceramic specifically, for example what packages to install and how to configure them, ideally at least covering the contents from https://developers.ceramic.network/reference/ but might be good to have more examples over time.
Cool, thanks for answering my questions everyone. I'm happy for this to be merged, but I know nothing about docusaurus (or, frankly, web development at all) so can't contribute to reviewing the actual code changes
Does this github action actually push the build to the
gh-pages
branch? cc @PaulLeCam
No looks like this is the action that only builds the website on PRs to main
, the deployment is another workflow that only runs on pushes to main
, with an extra step that deploys to GH pages: https://github.com/ceramicstudio/js-composedb/blob/main/.github/workflows/deploy-docs.yml