ceramicnetwork / docs Goto Github PK

Ceramic developer documentation site https://developers.ceramic.network

Home Page: https://developers.ceramic.network

HTML 100.00%

docs's Introduction

Ceramic Docs

This repo contains code and markdown files for the Ceramic documentation site. View the full site at developers.ceramic.network.

Contributing

We welcome all contributions – big and small. To contribute, make your change and submit a PR to this repo describing what you've done.

Installation

Follow these steps to run the site locally and test your changes if they're substantial.

Install pip

sudo apt-get install pip3

Mac with Python3 and Homebrew

brew install python3

Install mkdocs and related dependencies

pip3 install mkdocs mkdocs-material mkdocs-redirects

Build and run the docs server

mkdocs serve

Webserver with built docs should now be running and can be connected to in a browser at localhost:8000

Maintainers

License

Fully open sourced under MIT and Apache 2.

docs's People

Contributors

Stargazers

Watchers

docs's Issues

Add notes on indexing to docs

3 options to decide on based on uncertainty/scope:

Notion Known issues: https://www.notion.so/threebox/Known-Issues-16ae23c495f74b44af050555bc02d270
Docs
Blog post

Add callout about data wiping on 3Box nodes

We can add a few basic CSS styles which will allow us to create more visually interesting content layouts, which will increase comprehension and developer success. I'll follow up here with more detail.

Update home page

Describe config file in Hosting nodes section

Set up "was this page helpful"

This is another features offered through mkdocs material insiders

Create learn page for use cases

Include things like decentralized identity, p2p databases, evolutionary files, etc

Improve guide for running ceramic

Run Ceramic:
- run/index.md
- JS Ceramic:
  - run/js-ceramic/index.md
  - Running in the cloud: run/js-ceramic/running-in-the-cloud.md
  - Local installation: run/js-ceramic/installation.md
  - Switch networks: run/js-ceramic/switch-networks.md
  - Data persistence: run/js-ceramic/stream-management.md
  - Upgrades: run/js-ceramic/upgrades.md
  - Backup and Restore: run/js-ceramic/backup-and-restore.md
  - Advanced Options: run/js-ceramic/configuration-and-advanced-usage.md
  - Troubleshooting: run/js-ceramic/troubleshooting.md

Remove lambda section from hosting nodes

Clean up core flows

Based on the personas of the audience and what they're likely trying to accomplish or what they're looking for

Docs: The "copy to clipboard" button copies the `$` sign too

This is not a big issue, but more for convenience.

clicking on the "copy to clipboard" button adds this to the clipboard:

$ npm install @ceramicnetwork/http-client

Write intro/foundational topics

- Foundational Topics:
  - docs/foundational-topics/index.md
  - Networks: docs/foundational-topics/networks.md
  - Streams: docs/foundational-topics/streams.md
  - Accounts: docs/foundational-topics/accounts.md
  - Transactions: docs/foundational-topics/transactions.md
  - Nodes and Clients: docs/foundational-topics/nodes-and-clients.md
  - Consensus: docs/foundational-topics/consensus.md

Integrate Typedocs

From js-ceramic & js-did

Release Docs v1.2

https://www.notion.so/threebox/Ceramic-Docs-v2-f3dddb6244f24bbf87a2cd2391647d39

Write docs/advanced

Advanced:
- index.md
- Standards:
- docs/advanced/standards/index.md
- Stream program standards:
- docs/advanced/standards/stream-programs/index.md
- CIP-3 JSON Storage (TileDocument): index.md
- CIP-17 Crypto Account Links (CAIP10Link): index.md
- Application standards:
- docs/advanced/standards/application-protocols/index.md
- CIP-11 Account-based indexing (IDX): docs/advanced/standards/application-protocols/cip-11-account-based-stream- indexing.md
- Data model standards:
- docs/advanced/standards/data-models/index.md
- Data model universe: index.md
- Data model examples and patterns: index.md
- Account standards:
- CIP-4 3ID DID: authentication/3id-did/method.md
- PKH DID: index.md
- Key DID: authentication/key-did/method.md
- CIP-40 NFT DID: authentication/nft-did/method.md
- CIP-50 Safe DID: authentication/safe-did/method.md
- Indexing: docs/advanced/indexing.md
- Storage and backup: docs/advanced/storage-and-backup.md
- Privacy and access control: docs/advanced/privacy-and-access-control.md

Create intro/getting started guide

This is somewhat more involved as ideally we can set up the infrastructure first:

an embedded web shell, where a user clicks to connect, generates them a throwaway account, and they can paste code and have it execute using ceramic.js, did.js, key did provider and resolver,
Then we actually have to create the guide, which ideally is the user actually creating a simple hello world application like a microblog or social network application. I think this consists of 4 or 5 steps:

Deploy schemas (post, postIndex)
Store data (create two posts, add to post index)
Add to account (add post index to cip-11)
Query (query back)
Discover ()

Need to work through this

Write docs/* utility pages

Project:
- docs/project/index.md
- Roadmap: docs/project/roadmap.md
- Governance: docs/project/governance.md
- Code of Conduct: docs/project/code-of-conduct.md
- Security Issues: docs/project/security-issues.md
Community:
- docs/community/index.md
- Ways to contribute: docs/community/how-to-contribute.md
- Chat & discussion forums: docs/community/chat-and-discussion-forums.md
- Social media: docs/community/social-media.md

Document config file setup

Adding schema to "Writes" section

this commit removed the placeholder (non-working) schema from the write example, but I wonder if it would be helpful to include something like this preceeding the example, so that the user creates the doc with a real schema

  const schema = await ceramic.createDocument("tile", {
    content: {
      $schema: "http://json-schema.org/draft-07/schema#",
      title: "QuickStartSchema",
      type: "object",
      properties: {
        foo: { type: "string" },
      },
      required: ["foo"],
    },
    metadata: {
      controllers: [ceramic.did.id || ""],
      family: "schema",
    },
  })

On another note, I wonder if it would make sense to have a higher-level method to create a ceramic schema, similar to textile collections, that would type check the schema to ensure it's a valid JSONSchema prior to creating a document and returning a schema URL.

Another question... is there a "catalog" of predefined ceramic schemas somewhere? With the project I am trying to start up, WorldGraph, I hope to use interoperable schemas for linked data, similar to this example from schema.org, so that someone can browse the totality of linked data on ceramic using these known schemas. If this is an area that the ceramic team is interested in exploring, as it's a key capability for my project, I would be happy to research and come up with some proposals for a sort of schema registry. Let me know!

Write docs for 3ID lifecycle

Add docs on how to add a new streamtype

Improve installation docs

Link to quick start is broken

It's giving a 404:

https://developers.ceramic.network/build/quick-start/

Set up MkDocs material insiders

This will give us access to insiders features such as "was this page helpful", code annotations, better versioning, and other helpful things.

Add security overview page to docs

Add instructions for peerlist PR approval

-In your PR, you must include a description of setup for data persistence of multi address, Ceramic State Store and IPFS Repo. This is a critical step, as otherwise if your node restarts for any reason it will regenerate this file with a new address and all other nodes on the network will lose connection to your old multi address. (I feel like this part gets kind of lost in the box under data persistence, so might be good to be explicit here)
-You can view the multi address in the config file that IPFS creates. By default, it will be located in a directory call IPFS. The multi address includes the PeerID at the end. (I just noticed Catalyst guys seemed lost here, so might be helpful?)
-When you submit your PR, that will automatically trigger a test to make sure you’re successfully connected to the network. If this fails, we will reach out to you to triage the issue. Make sure there are no firewalls blocking your instance and that your port is properly exposed.

And include a link to this in the peerlist README

Include options for node hosting at different stages

@ukstv To include GCP!

Update docs to clarify when HTTP client needs DID Resolver

core client always needs did resolvers, the http client only needs it to do writes

Collapse learn/advanced into a dropdown

Docs: Import statement Typo

another minor issue! :)
here's the link: https://developers.ceramic.network/build/installation/

Example of self.id based app

Update readmes

https://www.notion.so/threebox/Ceramic-Docs-v2-f3dddb6244f24bbf87a2cd2391647d39

Write docs/intro pages

[ ] Introduction: docs/introduction/index.md
[ ] How Ceramic Works: docs/introduction/how-ceramic-works.md
[ ] Why Ceramic?: docs/introduction/why-ceramic.md
[ ] Ceramic compared to...: docs/introduction/comparisons.md

but not the getting started guide, which is in a different story

Clean up learn section

Add documentation for ethr did

Links on ceramic.network do not work on iPhone

Steps to reproduce:

Open the website in Safari
Open a side menu
Click on a menu link

Expectation: go to a page. Reality: nothing happens.

Improve welcome page

Include a summary on what Ceramic is and link to new pages that have been recently added

Write intro/foundational-topics

- Foundational Topics:
  - docs/foundational-topics/index.md
  - Networks: docs/foundational-topics/networks.md
  - Streams: docs/foundational-topics/streams.md
  - Accounts: docs/foundational-topics/accounts.md
  - Transactions: docs/foundational-topics/transactions.md
  - Nodes and Clients: docs/foundational-topics/nodes-and-clients.md
  - Consensus: docs/foundational-topics/consensus.md

Update to blockcodec-to-ipld-format

From discord:

cyph.err — Yesterday at 5:30 AM
the documentation here https://developers.ceramic.network/build/installation/#import-ipfs-with-dag-jose should be updated to use blockcodec-to-ipld-format instead of multiformats/legacy

Set up mike for versioning

This should be available through mkdocs insiders and somehow needs to be build into our deployment process on gh pages.

Add docs for new CRUD pinning API

Write docs/ceramic-stack

- Ceramic stack:
  - Intro to the stack: docs/ceramic-stack/introduction-to-the-stack.md
  - Stream programs:
    - docs/ceramic-stack/stream-programs/index.md
    - Stream program libraries: index.md
  - Data models:
    - docs/ceramic-stack/data-models/index.md
    - Data model libraries: index.md
    - Deploying data models: index.md
    - Composability: docs/ceramic-stack/data-models/composability.md
  - Client APIs:
    - docs/ceramic-stack/client-apis/index.md
    - Ceramic APIs:
      - docs/ceramic-stack/client-apis/ceramic/index.md
      - Ceramic JavaScript APIs: docs/ceramic-stack/client-apis/ceramic/javascript.md
      - Ceramic HTTP API: docs/ceramic-stack/client-apis/ceramic/http-api.md
    - Account APIs: 
      - docs/ceramic-stack/client-apis/accounts/index.md
      - Account JavaScript APIs: docs/ceramic-stack/client-apis/accounts/javascript.md
  - Development frameworks: docs/ceramic-stack/development-frameworks.md

Document consensus properties

With special attention to multi-writer streams

Add PR Templates to all Repos

Focus on keeping documentation up to date, relevant tests and more.

Update docs on how to create/query a deterministic tile

Document how to subscribe to updates on a stream

There are 2 things that should be covered.

When you load a Stream the content won't change by default - the handle you get has the state as of the point in time when it was loaded. But if you call .subscribe() on it, then the Stream handle will get subscribe to updates to the underlying log, and the contents within the Stream object can change over time

Some examples on how an app can subscribe to changes to a stream and take action on each new update. This is a little bit complicated/confusing right now because Stream is an Observable of StreamState, which means that if you subscribe to it the updates you get have a new StreamState object which is fairly low level and most devs won't know what to do with it. I wonder if we should try to change this so that Stream is an Observable of new Stream objects each tied to the point in time of each new state? So then app code could call subscribe() with a callback that gets a new Stream object each time, which will be more what they are accustomed to dealing with

how message signing works and what the messages are and how they need to be the same for DIDs generated to be the same
but this is also a good opportunity to better document 3ID Connect since it is such a core piece of tooling for many developers building applications on Ceramic