zeppelinos / zos-docs Goto Github PK

Docusaurus is able to handle different versions of a project, but we are not currently using this feature. Once we have more releases, it would be useful to have the reference section documentation reflect the different versions. The main hurdle with versioning is the syncing of the two repos: zos-lib and zos-cli.

Before tackling this, we probably want to have fully automated the reference section generation (#77).

Markdown file with an explanation of the Crafting Game from the perspective of ZeppelinOS.

Placeholder file in zos-docs/docs/docs/crafting.md. Keep current header:

---
id: crafting
title: Crafting
---

and don't add a top level (#) title.

Include which OZ contracts are available for use.

Duplicate zos-lib API home

https://github.com/zeppelinos/zos-docs/blob/69107bd713538fccc75f5a64602adca346d6d6d5/docs/docs/libmain.md

https://github.com/zeppelinos/zos-docs/blob/69107bd713538fccc75f5a64602adca346d6d6d5/docs/docs/api_libapi.md

Once we release 2.x on docs, we should review everything from a design perspective to make sure this sort of thing doesn't happen:

Markdown file with an explanation of Basil from the perspective of ZeppelinOS.

Placeholder file in zos-docs/docs/docs/basil.md. Keep current header:

---
id: basil
title: Basil
---

See gaTrakckingId parameter, https://docusaurus.io/docs/en/site-config.html#siteconfig-fields.

Right now, the reference section is generated in a partially automated form, using gen-docs for zos-cli, and solidity-docgen for zos-lib, and then pruning the corresponding outcomes and merging them manually.

We need to provide a script to do all of this, plus maybe the deployment, in a fully automated way. This will likely be most easily achieved by tweaking gen-docs (zeppelinos/zos-cli#143) and solidity-docgen to conform to the required pattern, and then simply merge with a script.

This pertains the generation of the .md files in the docs/docs/ folder, as well as the sidebars.json file. Finally, this is the first step towards having automated versioning for the docs (#78).

We wrote a guide in https://github.com/zeppelinos/zos-docs/blob/master/docs/docs/basil.md
However, the zos released version has some problems, so I haven't tested this end-to-end with the new release.

We need to make sure that a user can start from scratch and follow the entire guide without errors or confusions on the way.

Remove Basil and Crafty demo apps from doc site version for release 2.0

Part of OpenZeppelin/openzeppelin-labs#44.

Also known as README refactor, keep a minimal README.md in zeppelinos/zos-lib/, and refactor the rest of the contents to be hosted in zeppelinos/zos-docs/.

The contents of zeppelinos/zos-lib/README.md should be replicated in zeppelinos/zos-docs/docs/docs/libfront.md. There is a placeholder file there already, please keep the following header:

---
id: libfront
title: ZeppelinOS LIB API
sidebar_label: Library
---

This file should contain links to other .md files to be stored in zeppelinos/zos-docs/docs/docs/. A sidebar with these contents will be created for the Library, keep in mind that it doesn't allow nesting.

For consistency with previous guides.

Currently, we have two guides related to this new feature:

• How to use a stdlib
• How to develop a stdlib

We will need to update both using the new terminology (TBD). We should also make explicit that we are now able to handle multiple deps.

Automate extraction of description field of js commander in CLI commands to Markdown files to be used in the documentation site.

README is updated, modify with info on how to setup Docusaurus, and generate the CLI API and the Lib API. Still some manual tweaking required for integration.

Run doc-gen in the final MVP version and migrate the output files to zos-docs/docs/docs/.

The zos init subcommand should now take care of dealing with Truffle. Make sure the guides reflect the current usage.

Some use cases we may want to consider:

• Deploying upgradeable smart contracts programmatically
• Using EVM packages programmatically
• Building a sample app using EVM packages

On https://docs.zeppelinos.org/docs/stdlib.html zos-release points to a broken link. Is it no longer in a branch?

Produce a guide explaining the end-to-end process of developing smart contracts using ZeppelinOS in Markdown format.

Placeholder file at zos-docs/docs/docs/building.md. Please keep the header:

---
id: building
title: Building
---

[Moved to zos-docs/docs/docs/basil.md as Basil Demo].

We should consider the new content we are planning to add to the docs site and think about how it could be re-designed to arrange it in the most proper way to ensure a good experience for users.

Topics that will be added/updated:

• Add CLI commands documentation (OpenZeppelin/openzeppelin-sdk#148)
• Add a thorough documentation for lib contracts architecture (#18)
• Add contracts inline documentation (OpenZeppelin/openzeppelin-sdk#147)
• Add documentation for lib exported functions (#14)
• Add documentation for CLI exported scripts (OpenZeppelin/openzeppelin-sdk#149)
• Add token staking mechanics and usage (OpenZeppelin/openzeppelin-sdk#150)
• Add upgradeability pattern details (OpenZeppelin/openzeppelin-sdk#151)
• Update zos.json file docs with lightweight (#94)
• Update documentation and examples for multiple dependencies (#93)
• Migration guide from 1.x to 2.x
• Review current guides and content

On the end-to-end guide in https://github.com/zeppelinos/zos-docs/blob/master/docs/docs/basil.md we are documenting how to develop the application using a local test network.

We should end the guide by showing how to deploy and upgrade the contracts in a real network.

In https://docs.zeppelinos.org/docs/building.html (Building an upgradeable application), this is the command given to upgrade an application:

zos upgrade MyContract --network local

This command however is not available in version 1.1.0.

I believe the right command should be:

zos update MyContract --network local

docs/docs/stdlib.md currently only lists:

• DetailedMintableToken
• DetailedPremintedToken
• MintableERC721Token
• TokenTimelock
• TokenVesting

Add any newly included contracts.

Truffle does not know how to resolve functions with matching name but different arity, so contracts that inherit from certain openzeppelin-zos contracts, such as the mintable ones (which have both Ownable and DetailedToken initializers) will throw when their initialize function is called from truffle. zos create handles this fine, since it encodes the parameters on its own, but users will want to call initialize manually on their tests.

The current solution to this issue is to install zos-lib and use the same helper function zos create uses, encodeCall, which receives the signature of the function (including argument types) and the arguments, and crafts the call data, which can then be sent in a raw call. Example.

We should document this, at least in the advanced guide.

I'm strictly following the steps on https://docs.zeppelinos.org/docs/building.html and I get "Could not find suitable configuration file." when running "npx truffle compile". Maybe there's an extra step I should follow before running this command?

In zos-docs/docs/docs/building-upgradeable.md.

The API reference includes a link to the source of the contracts. For example, in:
https://docs.zeppelinos.org/docs/migrations_Initializable.html

This source link has this as the URL:
git+https://github.com/zeppelinos/zos-lib/blob/v0.1.12/contracts/migrations/Initializable.sol

The git+https is wrong, and can't be opened with the browser.

We are splitting the guides into one for deploying upgradeable contracts (#9) and one for using already deployed stdlibs (this issue).

Part of OpenZeppelin/openzeppelin-labs#44.

Consider https://github.com/zeppelinos/labs/tree/master/migrating_legacy_token_managed and https://github.com/zeppelinos/labs/tree/master/migrating_legacy_token_opt_in

In the Basil guide: https://github.com/zeppelinos/zos-docs/blob/master/docs/docs/basil.md#upgrading-a-contract, the following upgrade command is used:

zos upgrade Basil <proxy_address_1> --network development

Passing it <proxy_address_1> shouldn't be necessary.

The section should group technical detail about:
[x] storage structure
[x] initializers vs. constructors.

[ ] package.zos.json and package.zos.<network>.json files
This section is tackled in: (zeppelinos/zos-cli#36).

(as opposed to comma separated values)

see zeppelinos/zos-cli#170 (comment).