nevermined-io / docs-legacy Goto Github PK

The most relevant documentation is published here.

Nevermined as a digital ecosystems builder has some differences from a contracts deployment point of view compared
with some other protocols.

These are some main characteristics:

• We support different products built on Nevermined contracts running in different networks
• Each product will use different versions of the contracts
• Different products in the same network could require different versions of the contracts

Currently there is complexity to understand what artifacts are used where, specially when you take into account an architecture with several components.

The intention of this issue is to document a solution and agree on it.

The overall structure of the docs website is not very clear. It needs to be restructure. Potential TOC:

0. Intro
1. Overview
  1.1 What is Nevermined?
  1.2 For what is useful? (Use Cases)
  1.3 Why use Nevermined?
2. Architecture
  2.1 Specs
  2.2 Why do we use Blockchain?
  2.3 Building Blocks
  2.4 Technical components and repos
  2.5 Micro-Services
  2.6 SDKs
  2.7 Applications
3. NVM Integration
4. Tutorials
5. Tools
  5.1 Nevermined Tools
  5.2 CLI
6. NVM Environments
7. Blog Posts
8. License

Automate the documentation from Swagger v2 to a format that can be converted to Markdown and shown on docs.nevermined.io. Document:

• Gateway API
• Metadata API

Currently we don't have a common approach to document contracts, specs, libraries, apis across the board.

The intention of this task is to investigate how we could document all the technical components in such a way we can provide a unique documentation site where different kind of users can understand about Nevermined, how to integrate, tutorials and each independent component.

We can evaluate things like:
https://docusaurus.io
https://github.com/slatedocs/slate
https://www.gitbook.com/

Steps:

• Document the architecture
• Review
• Update Nevermined Provenance Spec

Docusaurus requires a format constraints in order to compile the markdown files into htmls.
Some of the nevermined projects generates documentation that is not compatible with Docusaurus.
For example marketplace-api generated md from json using widdershins is not compatible with Docusaurus format out of the box. Reading some comments on GitHub seems possible to use widdershins templates to make it compatible.
Other projects can be affected by the same problem.

List of projects docs that need to be reviewed:

• Marketplace-api: Review Format for the api. Add written docs (not just API doc)
• Gateway: Current yml docs are not compatible with Docusaurus. Need to be adapted. --> Disabled trigger. Issue.
• Gateway-ts: The openapi.json in the docs belongs to marketplace-api. Need to be updated. Issue.

The following issue includes:

• Review the existing nevermined docs sections regarding the sdks
• Compare the state of the Js, Py and Java versions of the SDKs
• Generate a unified SDK structure
• Modify the SDK's to use the new structure
• Document the SDKs APIs
• CLI Documentation

Description

In Metadata object the parameter serviceAgreementTemplate is not documented in Nevermined docs

Where

https://github.com/nevermined-io/docs/blob/master/docs/architecture/specs/examples/metadata/v0.2/ddo-example-access.json#L123

Acceptance criteria

• serviceAgreementTemplate parameter object need to be documented like the rest of the parameters

Effort

medium

Impact

medium

The docs website will fail to build if there are any broken links.

Projects should lint the markdown and mdx files with something like remark-lint and https://github.com/davidtheclark/remark-lint-no-dead-urls to check for dead urls and other problems

Migrating to mkdocs

The docs repository of Nevermined must be a key point to communicate how users can use/integrate Nevermined. Currently this documentation is disperse, not up to date and not complete.

The main motivation of this epic is to prepare a documentation portal where we have from top to bottom all the information required about Nevermined. Attracting users to Nevermined and facilitate the protocol adoption is key, so the documentation must be clear, easy to understand and facilitate users adoption and DevExp.

Tasks:

• nevermined-io/docs#46
• https://github.com/nevermined-io/internal/issues/229
• All the documentation must be consolidated in the docs website
• We must have documentation explaining the core protocol
• We must have good documentation about CLI
• We must have good documentation about contracts
• We must have good documentation about sdk-js
• We must have good documentation about the components catalog
• nevermined-io/sdk-js#149

It would be necessary to write a blog post speaking about the Nevermined Control Center, including features, for what is useful and potential next steps.

This can be a high-level post, we can go deeper in some compute stuff in further posts.

• We must have good documentation about the search queries
• https://github.com/nevermined-io/internal/issues/246
• #64
• #65
• #66
• #67
• #68
• #69
• #70
• #71
• #72
• #73
• #74
• #75
• #76
• #77
• #78
• #79
• #80
• #81
• #82
• #83
• #84
• Write a blog post to introduce the new docs website
• #86
• Have a Nevermined Docs logo instead of just text similar to top-left https://ionicframework.com/docs
• #85

Look & Feel

• This doesn't have any sense

Description

In the section of the documentation of Metadata Additional Attributes there is not types neither examples to use as a reference in order to validate the payload

Where

https://docs.nevermined.io/architecture/specs/metadata/#other-suggested-additional-attributes

Acceptance criteria

Types and examples should be added for each parameter

Effort

low

Impact

medium

The Swagger-api json doc from gateway-ts is a copy of the Marketplace-API documentation (i.e.: It does not describe Gateway API).

Also the documentation from gateway is not compatible with widdershins and cannot be converted to be used with Docusaurius, so the documentation in gateway-ts should be the swagger-api doc in json format.

• Catalog
• SDK JS