Skip to content

Commit 4fafa36

Browse files
SebastienGllmtSebastienGllmt
authored
First draft for documentation (#52)
1 parent 478e8c4 commit 4fafa36

11 files changed

+305
-62
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
node_modules/
22
publish/
33
rust/target
4+
.vscode/

‎.readthedocs.yml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
2+
version: 2
3+
4+
sphinx:
5+
configuration: doc/conf.py
6+
7+
# Optionally set the version of Python and requirements required to build your docs
8+
python:
9+
version: 3.7
10+
install:
11+
- requirements: doc/.sphinx/requirements.txt

‎README.md

+1-62
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
This is a library for serialization & deserialization of data structures used in Cardano's Haskell implementation of Shelley along with useful utility functions.
44

5-
## How can I use this library
6-
7-
Rust is wonderfully portable! You can easily bind to the native Rust library from any common programming language (even C and WebAssembly)!
8-
95
##### NPM packages
106

117
- [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
1511

1612
- [React-Native mobile bindings](https://github.com/Emurgo/react-native-haskell-shelley)
1713

18-
## Benefits of using this library
19-
20-
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!
21-
22-
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!
23-
24-
Powerful and flexible enough to be used to power wallets and exchanges! (Yes, it's used in production!)
25-
2614
## Documentation
2715

28-
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!
29-
You can find the Flow types [here](/rust/pkg/cardano_serialization_lib.js.flow)
30-
31-
You can also look in the [example](/example) folder to see how to use this library from Typescript or just experiment with the library.
32-
33-
## What about other versions of Cardano?
34-
35-
If you are looking for legacy bindings, you can find them at the following:
36-
37-
- [Byron WASM bindings](https://github.com/input-output-hk/js-cardano-wasm/tree/master/cardano-wallet)
38-
- [Jormungandr WASM bindings](https://github.com/emurgo/js-chain-libs)
39-
40-
## Original binary specifications
41-
42-
Here are the location of the original [CDDL](http://cbor.io/tools.html) specifications:
43-
44-
- Byron: [link](https://github.com/input-output-hk/cardano-ledger-specs/tree/master/byron/cddl-spec)
45-
- Shelley: [link](https://github.com/input-output-hk/cardano-ledger-specs/tree/master/shelley/chain-and-ledger/executable-spec/cddl-files)
46-
47-
## Building
48-
49-
If you need to install Rust, do the following:
50-
```
51-
curl https://sh.rustup.rs -sSf | sh -s -- -y
52-
echo 'export PATH=$HOME/.cargo/bin/:$PATH' >> $BASH_ENV
53-
rustup install stable
54-
rustup target add wasm32-unknown-unknown --toolchain stable
55-
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
56-
```
57-
58-
To build this repository, do the following:
59-
```
60-
git submodule update --init --recursive
61-
nvm use
62-
npm install
63-
npm run rust:build-nodejs
64-
```
65-
66-
## Testing
67-
68-
```
69-
npm run rust:test
70-
```
71-
72-
## Publishing
73-
74-
```
75-
npm run js:publish-nodejs
76-
npm run js:publish-browser
77-
```
16+
You can find documentation [here](https://docs.cardano.org/projects/cardano-serialization-lib/en/latest/)

‎README.rst

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
Cardano Serialization Lib
2+
=========================
3+
4+
This is a library for serialization & deserialization of data structures
5+
used in Cardano’s Haskell implementation of Shelley along with useful
6+
utility functions.
7+
8+
How can I use this library
9+
--------------------------
10+
11+
Rust is wonderfully portable! You can easily bind to the native Rust
12+
library from any common programming language (even C and WebAssembly)!
13+
14+
NPM packages
15+
''''''''''''
16+
17+
- `NodeJS WASM package`_
18+
- `Browser (chrome/firefox) WASM package`_
19+
20+
Mobile bindings
21+
'''''''''''''''
22+
23+
- `React-Native mobile bindings`_
24+
25+
Benefits of using this library
26+
------------------------------
27+
28+
Serialization/deserialization code is automatically generated from
29+
Cardano’s official specification, which guarantees it can easily stay up
30+
to date! We do this using an EMURGO-written tool called `cddl-codegen`_
31+
which can be re-used for other tasks such as automatically generate a
32+
Rust library for Cardano metadata specifications!
33+
34+
It is also very easy to create scripts in Rust or WASM to share with
35+
stake pools, or even embed inside an online tool! No more crazy
36+
cardano-cli bash scripts!
37+
38+
Powerful and flexible enough to be used to power wallets and exchanges!
39+
(Yes, it’s used in production!)
40+
41+
Documentation
42+
-------------
43+
44+
This library generates both `Typescript`_ and `Flow`_ type definitions,
45+
so it’s often easiest to see what is possible by just looking at the
46+
types! You can find the Flow types `here`_
47+
48+
You can also look in the `example`_ folder to see how to use this
49+
library from Typescript or just experiment with the library.
50+
51+
What about other versions of Cardano?
52+
-------------------------------------
53+
54+
If you are looking for legacy bindings, you can find them at the
55+
following:
56+
57+
- `Byron WASM bindings`_
58+
- `Jormungandr WASM bindings`_
59+
60+
Original binary specifications
61+
------------------------------
62+
63+
Here are the location of the original `CDDL`_ specifications:
64+
65+
- Byron: `link`_
66+
- Shelley:
67+
`link <https://github.com/input-output-hk/cardano-ledger-specs/tree/master/shelley/chain-and-ledger/executable-spec/cddl-files>`__
68+
69+
Building
70+
--------
71+
72+
If you need to install Rust, do the following:
73+
74+
::
75+
76+
curl https://sh.rustup.rs -sSf | sh -s -- -y
77+
echo 'export PATH=$HOME/.cargo/bin/:$PATH' >> $BASH_ENV
78+
rustup install stable
79+
rustup target add wasm32-unknown-unknown --toolchain stable
80+
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
81+
82+
To build this repository, do the following:
83+
84+
::
85+
86+
git submodule update --init --recursive
87+
nvm use
88+
npm install
89+
npm run rust:build-nodejs
90+
91+
Testing
92+
-------
93+
94+
::
95+
96+
npm run rust:test
97+
98+
Publishing
99+
----------
100+
101+
To publish new versions to NPM (only needed if you are an admin of this project)
102+
::
103+
104+
npm run js:publish-nodejs
105+
npm run js:publish-browser
106+
107+
.. _NodeJS WASM package: https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs
108+
.. _Browser (chrome/firefox) WASM package: https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser
109+
.. _React-Native mobile bindings: https://github.com/Emurgo/react-native-haskell-shelley
110+
.. _cddl-codegen: https://github.com/Emurgo/cddl-codegen
111+
.. _Typescript: https://www.typescriptlang.org/
112+
.. _Flow: https://flow.org/
113+
.. _here: /rust/pkg/cardano_serialization_lib.js.flow
114+
.. _example: /example
115+
.. _Byron WASM bindings: https://github.com/input-output-hk/js-cardano-wasm/tree/master/cardano-wallet
116+
.. _Jormungandr WASM bindings: https://github.com/emurgo/js-chain-libs
117+
.. _CDDL: http://cbor.io/tools.html
118+
.. _link: https://github.com/input-output-hk/cardano-ledger-specs/tree/master/byron/cddl-spec

‎doc/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/

‎doc/.sphinx/_templates/layout.html

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{% extends "!layout.html" %}
2+
3+
{% block footer %}
4+
{{ super() }}
5+
<div class="footer">YEP THIS IS AN EXAMPLE
6+
</div>
7+
{% endblock %}

‎doc/.sphinx/cardano-logo.png

14.8 KB
Loading

‎doc/.sphinx/requirements.txt

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Sphinx==3.1.1
2+
sphinx-intl==2.0.1
3+
transifex-client==0.13.10
4+
testresources==2.0.1
5+
-e git+https://github.com/input-output-hk/sphinx_rtd_theme.git#egg=sphinx_rtd_theme
6+
recommonmark==0.6
7+
## The following requirements were added by pip freeze:
8+
alabaster==0.7.12
9+
Babel==2.8.0
10+
certifi==2020.4.5.2
11+
chardet==3.0.4
12+
click==7.1.2
13+
sphinxcontrib-mermaid==0.4.0
14+
sphinxemoji==0.1.6
15+
sphinx_markdown_tables==0.0.15
16+
CommonMark==0.9.1
17+
docutils==0.16
18+
future==0.18.2
19+
idna==2.9
20+
imagesize==1.2.0
21+
Jinja2==2.11.2
22+
jsonpointer==2.0
23+
jsonref==0.2
24+
MarkupSafe==1.1.1
25+
Pygments==2.6.1
26+
pytz==2020.1
27+
requests==2.24.0
28+
six==1.15.0
29+
snowballstemmer==2.0.0
30+
sphinxcontrib-websupport==1.2.2
31+
urllib3==1.25.9

‎doc/conf.py

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
2+
3+
import sys
4+
import os
5+
import sphinx_rtd_theme
6+
import recommonmark
7+
8+
from recommonmark.transform import AutoStructify
9+
from os.path import abspath, join, dirname
10+
11+
sys.path.insert(0, abspath(join(dirname(__file__))))
12+
13+
# -- RTD configuration ------------------------------------------------
14+
15+
on_rtd = os.environ.get("READTHEDOCS", None) == "True"
16+
17+
# This is used for linking and such so we link to the thing we're building
18+
rtd_version = os.environ.get("READTHEDOCS_VERSION", "latest")
19+
if rtd_version not in ["stable", "latest"]:
20+
rtd_version = "stable"
21+
22+
# -- Project information -----------------------------------------------------
23+
24+
project = 'cardano-serialization-lib Documentation'
25+
copyright = '2020, EMURGO'
26+
author = 'EMURGO'
27+
28+
# The full version, including alpha/beta/rc tags
29+
release = '1.0.0'
30+
31+
32+
# -- General configuration ---------------------------------------------------
33+
master_doc = 'index'
34+
# Add any Sphinx extension module names here, as strings. They can be
35+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
36+
# ones.
37+
38+
extensions = [
39+
"sphinx_rtd_theme",
40+
'recommonmark',
41+
'sphinx_markdown_tables',
42+
'sphinxemoji.sphinxemoji',
43+
"sphinx.ext.autodoc",
44+
"sphinx.ext.autosummary",
45+
"sphinx.ext.intersphinx",
46+
"sphinx.ext.viewcode",
47+
]
48+
49+
# Add any paths that contain templates here, relative to this directory.
50+
templates_path = ['.sphinx/_templates']
51+
html_static_path = ['.sphinx/_static']
52+
53+
source_suffix = {
54+
'.rst': 'restructuredtext',
55+
'.md': 'markdown',
56+
}
57+
58+
intersphinx_mapping = {
59+
"commandsv1": (
60+
"https://robotpy.readthedocs.io/projects/commands-v1/en/%s/"
61+
% rtd_version,
62+
None,
63+
),
64+
}
65+
66+
# List of patterns, relative to source directory, that match files and
67+
# directories to ignore when looking for source files.
68+
# This pattern also affects html_static_path and html_extra_path.
69+
exclude_patterns = []
70+
71+
72+
# -- Options for HTML output -------------------------------------------------
73+
74+
# The theme to use for HTML and HTML Help pages. See the documentation for
75+
# a list of builtin themes.
76+
#
77+
html_theme = "sphinx_rtd_theme"
78+
79+
html_theme_options = {
80+
'logo_only': False,
81+
'display_version': False,
82+
'prev_next_buttons_location': 'bottom',
83+
'style_external_links': False,
84+
'style_nav_header_background': '#fcfcfc',
85+
# Toc options
86+
'collapse_navigation': True,
87+
'sticky_navigation': True,
88+
'navigation_depth': 4,
89+
'includehidden': True,
90+
'titles_only': False
91+
}
92+
93+
# Add any paths that contain custom static files (such as style sheets) here,
94+
# relative to this directory. They are copied after the builtin static files,
95+
# so a file named "default.css" will overwrite the builtin "default.css".
96+
97+
html_logo = ".sphinx/cardano-logo.png"
98+
99+
html_context = {
100+
"display_github": True, # Add 'Edit on Github' link instead of 'View page source'
101+
"github_user": "Emurgo",
102+
"github_repo": "cardano-serialization-lib",
103+
"github_version": "master",
104+
"conf_py_path": "/",
105+
"source_suffix": source_suffix,
106+
}
107+
108+
# -- Custom Document processing ----------------------------------------------
109+
110+
def setup(app):
111+
app.add_config_value('recommonmark_config', {
112+
'enable_auto_doc_ref': False,
113+
'enable_auto_toc_tree': False,
114+
}, True)
115+
app.add_transform(AutoStructify)

‎doc/getting-started/prerequisite-knowledge.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Pre-requisite knowledge
2+
3+
This library assumes a certain amount of knowledge about how Cardano works (want to avoid re-documenting the wheel).
4+
5+
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.

‎doc/index.rst

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. include:: ../README.rst
2+
3+
.. toctree::
4+
:titlesonly:
5+
:hidden:
6+
7+
Go Back to Cardano Documentation <https://cardano.readthedocs.io>
8+
9+
.. toctree::
10+
:maxdepth: 3
11+
:caption: Getting Started
12+
:titlesonly:
13+
:hidden:
14+
15+
getting-started/prerequisite-knowledge

0 commit comments

Comments
 (0)