First draft for documentation (Emurgo#52)

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 publish/
 rust/target
+.vscode/

.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

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/)

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 <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
+----------
+
+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

doc/.gitignore

@@ -0,0 +1 @@
+_build/

doc/.sphinx/_templates/layout.html

@@ -0,0 +1,7 @@
+{% extends "!layout.html" %}
+
+{% block footer %}
+{{ super() }}
+<div class="footer">YEP THIS IS AN EXAMPLE
+</div>
+{% endblock %}

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

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)

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.

doc/index.rst

@@ -0,0 +1,15 @@
+.. include:: ../README.rst
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   Go Back to Cardano Documentation <https://cardano.readthedocs.io>
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Getting Started
+   :titlesonly:
+   :hidden:
+
+   getting-started/prerequisite-knowledge