diff --git a/.gitignore b/.gitignore index 00fd270e..9802fe48 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ node_modules/ publish/ rust/target +.vscode/ \ No newline at end of file diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..5853a2b5 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,11 @@ + +version: 2 + +sphinx: + configuration: doc/conf.py + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: doc/.sphinx/requirements.txt \ No newline at end of file diff --git a/README.md b/README.md index 9e766e90..a5efcf60 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,6 @@ This is a library for serialization & deserialization of data structures used in Cardano's Haskell implementation of Shelley along with useful utility functions. -## How can I use this library - -Rust is wonderfully portable! You can easily bind to the native Rust library from any common programming language (even C and WebAssembly)! - ##### NPM packages - [NodeJS WASM package](https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs) @@ -15,63 +11,6 @@ Rust is wonderfully portable! You can easily bind to the native Rust library fro - [React-Native mobile bindings](https://github.com/Emurgo/react-native-haskell-shelley) -## Benefits of using this library - -Serialization/deserialization code is automatically generated from Cardano's official specification, which guarantees it can easily stay up to date! We do this using an EMURGO-written tool called [cddl-codegen](https://github.com/Emurgo/cddl-codegen) which can be re-used for other tasks such as automatically generate a Rust library for Cardano metadata specifications! - -It is also very easy to create scripts in Rust or WASM to share with stake pools, or even embed inside an online tool! No more crazy cardano-cli bash scripts! - -Powerful and flexible enough to be used to power wallets and exchanges! (Yes, it's used in production!) - ## Documentation -This library generates both [Typescript](https://www.typescriptlang.org/) and [Flow](https://flow.org/) type definitions, so it's often easiest to see what is possible by just looking at the types! -You can find the Flow types [here](/rust/pkg/cardano_serialization_lib.js.flow) - -You can also look in the [example](/example) folder to see how to use this library from Typescript or just experiment with the library. - -## What about other versions of Cardano? - -If you are looking for legacy bindings, you can find them at the following: - -- [Byron WASM bindings](https://github.com/input-output-hk/js-cardano-wasm/tree/master/cardano-wallet) -- [Jormungandr WASM bindings](https://github.com/emurgo/js-chain-libs) - -## Original binary specifications - -Here are the location of the original [CDDL](http://cbor.io/tools.html) specifications: - -- Byron: [link](https://github.com/input-output-hk/cardano-ledger-specs/tree/master/byron/cddl-spec) -- Shelley: [link](https://github.com/input-output-hk/cardano-ledger-specs/tree/master/shelley/chain-and-ledger/executable-spec/cddl-files) - -## Building - -If you need to install Rust, do the following: -``` -curl https://sh.rustup.rs -sSf | sh -s -- -y -echo 'export PATH=$HOME/.cargo/bin/:$PATH' >> $BASH_ENV -rustup install stable -rustup target add wasm32-unknown-unknown --toolchain stable -curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh -``` - -To build this repository, do the following: -``` -git submodule update --init --recursive -nvm use -npm install -npm run rust:build-nodejs -``` - -## Testing - -``` -npm run rust:test -``` - -## Publishing - -``` -npm run js:publish-nodejs -npm run js:publish-browser -``` +You can find documentation [here](https://docs.cardano.org/projects/cardano-serialization-lib/en/latest/) \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..b4d8a7d1 --- /dev/null +++ b/README.rst @@ -0,0 +1,118 @@ +Cardano Serialization Lib +========================= + +This is a library for serialization & deserialization of data structures +used in Cardano’s Haskell implementation of Shelley along with useful +utility functions. + +How can I use this library +-------------------------- + +Rust is wonderfully portable! You can easily bind to the native Rust +library from any common programming language (even C and WebAssembly)! + +NPM packages +'''''''''''' + +- `NodeJS WASM package`_ +- `Browser (chrome/firefox) WASM package`_ + +Mobile bindings +''''''''''''''' + +- `React-Native mobile bindings`_ + +Benefits of using this library +------------------------------ + +Serialization/deserialization code is automatically generated from +Cardano’s official specification, which guarantees it can easily stay up +to date! We do this using an EMURGO-written tool called `cddl-codegen`_ +which can be re-used for other tasks such as automatically generate a +Rust library for Cardano metadata specifications! + +It is also very easy to create scripts in Rust or WASM to share with +stake pools, or even embed inside an online tool! No more crazy +cardano-cli bash scripts! + +Powerful and flexible enough to be used to power wallets and exchanges! +(Yes, it’s used in production!) + +Documentation +------------- + +This library generates both `Typescript`_ and `Flow`_ type definitions, +so it’s often easiest to see what is possible by just looking at the +types! You can find the Flow types `here`_ + +You can also look in the `example`_ folder to see how to use this +library from Typescript or just experiment with the library. + +What about other versions of Cardano? +------------------------------------- + +If you are looking for legacy bindings, you can find them at the +following: + +- `Byron WASM bindings`_ +- `Jormungandr WASM bindings`_ + +Original binary specifications +------------------------------ + +Here are the location of the original `CDDL`_ specifications: + +- Byron: `link`_ +- Shelley: + `link `__ + +Building +-------- + +If you need to install Rust, do the following: + +:: + + curl https://sh.rustup.rs -sSf | sh -s -- -y + echo 'export PATH=$HOME/.cargo/bin/:$PATH' >> $BASH_ENV + rustup install stable + rustup target add wasm32-unknown-unknown --toolchain stable + curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh + +To build this repository, do the following: + +:: + + git submodule update --init --recursive + nvm use + npm install + npm run rust:build-nodejs + +Testing +------- + +:: + + npm run rust:test + +Publishing +---------- + +To publish new versions to NPM (only needed if you are an admin of this project) +:: + + npm run js:publish-nodejs + npm run js:publish-browser + +.. _NodeJS WASM package: https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs +.. _Browser (chrome/firefox) WASM package: https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser +.. _React-Native mobile bindings: https://github.com/Emurgo/react-native-haskell-shelley +.. _cddl-codegen: https://github.com/Emurgo/cddl-codegen +.. _Typescript: https://www.typescriptlang.org/ +.. _Flow: https://flow.org/ +.. _here: /rust/pkg/cardano_serialization_lib.js.flow +.. _example: /example +.. _Byron WASM bindings: https://github.com/input-output-hk/js-cardano-wasm/tree/master/cardano-wallet +.. _Jormungandr WASM bindings: https://github.com/emurgo/js-chain-libs +.. _CDDL: http://cbor.io/tools.html +.. _link: https://github.com/input-output-hk/cardano-ledger-specs/tree/master/byron/cddl-spec diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..c6a151b3 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +_build/ \ No newline at end of file diff --git a/doc/.sphinx/_templates/layout.html b/doc/.sphinx/_templates/layout.html new file mode 100644 index 00000000..661a1d96 --- /dev/null +++ b/doc/.sphinx/_templates/layout.html @@ -0,0 +1,7 @@ +{% extends "!layout.html" %} + +{% block footer %} +{{ super() }} +
YEP THIS IS AN EXAMPLE +
+{% endblock %} \ No newline at end of file diff --git a/doc/.sphinx/cardano-logo.png b/doc/.sphinx/cardano-logo.png new file mode 100644 index 00000000..7233b4fb Binary files /dev/null and b/doc/.sphinx/cardano-logo.png differ diff --git a/doc/.sphinx/requirements.txt b/doc/.sphinx/requirements.txt new file mode 100644 index 00000000..271738b0 --- /dev/null +++ b/doc/.sphinx/requirements.txt @@ -0,0 +1,31 @@ +Sphinx==3.1.1 +sphinx-intl==2.0.1 +transifex-client==0.13.10 +testresources==2.0.1 +-e git+https://github.com/input-output-hk/sphinx_rtd_theme.git#egg=sphinx_rtd_theme +recommonmark==0.6 +## The following requirements were added by pip freeze: +alabaster==0.7.12 +Babel==2.8.0 +certifi==2020.4.5.2 +chardet==3.0.4 +click==7.1.2 +sphinxcontrib-mermaid==0.4.0 +sphinxemoji==0.1.6 +sphinx_markdown_tables==0.0.15 +CommonMark==0.9.1 +docutils==0.16 +future==0.18.2 +idna==2.9 +imagesize==1.2.0 +Jinja2==2.11.2 +jsonpointer==2.0 +jsonref==0.2 +MarkupSafe==1.1.1 +Pygments==2.6.1 +pytz==2020.1 +requests==2.24.0 +six==1.15.0 +snowballstemmer==2.0.0 +sphinxcontrib-websupport==1.2.2 +urllib3==1.25.9 diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..a4e912db --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,115 @@ + + +import sys +import os +import sphinx_rtd_theme +import recommonmark + +from recommonmark.transform import AutoStructify +from os.path import abspath, join, dirname + +sys.path.insert(0, abspath(join(dirname(__file__)))) + +# -- RTD configuration ------------------------------------------------ + +on_rtd = os.environ.get("READTHEDOCS", None) == "True" + +# This is used for linking and such so we link to the thing we're building +rtd_version = os.environ.get("READTHEDOCS_VERSION", "latest") +if rtd_version not in ["stable", "latest"]: + rtd_version = "stable" + +# -- Project information ----------------------------------------------------- + +project = 'cardano-serialization-lib Documentation' +copyright = '2020, EMURGO' +author = 'EMURGO' + +# The full version, including alpha/beta/rc tags +release = '1.0.0' + + +# -- General configuration --------------------------------------------------- +master_doc = 'index' +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +extensions = [ + "sphinx_rtd_theme", + 'recommonmark', + 'sphinx_markdown_tables', + 'sphinxemoji.sphinxemoji', + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.sphinx/_templates'] +html_static_path = ['.sphinx/_static'] + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +intersphinx_mapping = { + "commandsv1": ( + "https://robotpy.readthedocs.io/projects/commands-v1/en/%s/" + % rtd_version, + None, + ), +} + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +html_theme_options = { + 'logo_only': False, + 'display_version': False, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + 'style_nav_header_background': '#fcfcfc', + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". + +html_logo = ".sphinx/cardano-logo.png" + +html_context = { + "display_github": True, # Add 'Edit on Github' link instead of 'View page source' + "github_user": "Emurgo", + "github_repo": "cardano-serialization-lib", + "github_version": "master", + "conf_py_path": "/", + "source_suffix": source_suffix, +} + +# -- Custom Document processing ---------------------------------------------- + +def setup(app): + app.add_config_value('recommonmark_config', { + 'enable_auto_doc_ref': False, + 'enable_auto_toc_tree': False, + }, True) + app.add_transform(AutoStructify) \ No newline at end of file diff --git a/doc/getting-started/prerequisite-knowledge.md b/doc/getting-started/prerequisite-knowledge.md new file mode 100644 index 00000000..66114f6a --- /dev/null +++ b/doc/getting-started/prerequisite-knowledge.md @@ -0,0 +1,5 @@ +# Pre-requisite knowledge + +This library assumes a certain amount of knowledge about how Cardano works (want to avoid re-documenting the wheel). + +You can find the specifications of Cardano's ledger [here](https://github.com/input-output-hk/cardano-ledger-specs) which we suggest consulting as you use this library. Notably, the `Shelley ledger formal specification` covers the core concepts. diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..0e8d8453 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,15 @@ +.. include:: ../README.rst + +.. toctree:: + :titlesonly: + :hidden: + + Go Back to Cardano Documentation + +.. toctree:: + :maxdepth: 3 + :caption: Getting Started + :titlesonly: + :hidden: + + getting-started/prerequisite-knowledge \ No newline at end of file