Added Solidity version of the ownership/states/assets tutorial.

solidity_user_guide/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

solidity_user_guide/requirements.txt

@@ -0,0 +1 @@
+pygments-lexer-solidity

solidity_user_guide/source/conf.py

@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import sphinx_rtd_theme
+
+def setup(sphinx):
+    from pygments_lexer_solidity import SolidityLexer
+    sphinx.add_lexer('Solidity', SolidityLexer())
+
+# -- Project information -----------------------------------------------------
+
+project = u'Solidity'
+copyright = u'2019, Michael Coblenz and Obsidian Project Contributors'
+author = u'Michael Coblenz'
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u'0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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.ext.todo',
+    'sphinx_rtd_theme',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# 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 = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+highlight_language = 'Solidity'
+
+# -- 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'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# 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_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Solidityndoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Solidity.tex', u'Solidity Documentation',
+     u'Michael Coblenz', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'solidity', u'Solidity Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Solidity', u'Solidity Documentation',
+     author, 'Solidity', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True

solidity_user_guide/source/getting_started.rst

@@ -0,0 +1,4 @@
+Getting Started
+===============
+
+TODO

solidity_user_guide/source/index.rst

@@ -0,0 +1,21 @@
+.. Obsidian documentation master file, created by
+   sphinx-quickstart on Fri Aug 23 13:39:43 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+The Solidity Smart Contract Language
+======================================
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   Getting Started <getting_started>
+   Solidity Language Tutorial <tutorial/tutorial>
+   Solidity Reference <reference/reference>
+
+
+
+Solidity is an object-oriented language for smart contracts.
+
+Even if you are highly experienced with OOP, you will find that by using special programming techniques, you can program much more safely, avoiding bugs that would otherwise be common. We recommend that you read the sections of the manual on *ownership* and *states* before you write your first Solidity program.

solidity_user_guide/source/reference/basics.rst

@@ -0,0 +1,28 @@
+Solidity Language Basics
+==========================
+
+Contracts, functions, and main contracts
+----------------------------------------------
+Solidity is object-oriented. A ``contract`` is like a class: it can be instantiated as many times as needed. Each contract supports operations; each one is called a ``function``. Functions are akin to methods in traditional object-oriented languages. However, unlike methods, functions either completely finish or revert. If a function reverts (via the ``revert`` statement), then all changes that the function made will be discarded.
+
+Visibility
+--------------
+Constructors, functions, etc. must specify *visibility*: `public`, `external`, `internal`, or `private`. For this guide, `public` suffices; it means that the function can be called both within the contract and from other contracts.
+
+Constructors
+------------
+Constructors must initialize all the fields of their contracts. Constructors are defined with the ``constructor`` keyword. For example:
+
+::
+
+   pragma solidity ^0.5.1;
+   
+   contract LightSwitch {
+      enum SwitchState {Off, On}
+
+      SwitchState state;
+
+      constructor() public {
+         state = SwitchState.Off;
+      }
+   }

solidity_user_guide/source/reference/reference.rst

@@ -0,0 +1,7 @@
+Obsidian Language Reference
+============================
+
+Before using this reference guide, please read the entire tutorial first, since the reference guide uses concepts explained in the tutorial.
+
+.. toctree::
+   Language Basics <basics>

solidity_user_guide/source/tutorial/assets.rst

@@ -0,0 +1,44 @@
+Assets
+======
+Some owning references are to things that should not be accidentally lost. To help prevent accidental loss, we can mark contracts as *assets*. Let's do this for ``Money``:
+
+::
+
+   contract Money { // Money is an asset
+   }
+
+Now, it is the programmer's responsibility to pay special attention to owned references to assets. For example:
+
+::
+
+   function test() public {
+      Money m = ...; // Assume m is owned here
+      // BUG: Money is an asset, so owned references should not be allowed to go out of scope!
+   }
+
+
+We can fix this by (for example) returning m, assigning it to an owning field, or passing it as an argument to an appropriate function. For example:
+
+::
+
+   function test() public returns (Money) { // returns an owned reference
+      Money m = ...; // assume m is owned
+      return m; // gives ownership of m to the caller of test()
+   }
+
+NOTE: non-owning references to ``Money`` are not restricted; there's no problem with letting them go out of scope.
+
+States and Assets
+------------------
+
+States can also be marked as ``asset`` s, which means the contract is an asset (see Part 4) only when in that state.
+For example, see an alternate definition of ``Wallet`` below, in which a ``Wallet`` is an  ``asset`` only
+when it is ``Full``. 
+
+::
+
+   contract Wallet {
+      asset state Full;
+      state Empty;
+   }
+

solidity_user_guide/source/tutorial/ownership1.rst

@@ -0,0 +1,58 @@
+Ownership -- Introduction
+=============================================================
+
+
+.. highlight:: Solidity
+
+
+
+Solidity is object-oriented. It includes *contracts*, which are like classes, and can have *fields* 
+and *functions*, analogous to Java fields and methods respectively. 
+
+In order to use Solidity effectively, we suggest applying *ownership* to clarify the relationships between objects. In this section of the tutorial, you will learn about ownership.
+
+Objects can be *owned*, in which *one of the references* to the object is owned. An owned object can have any number of unowned references. Alternatively, if the object is not owned, 
+it can have any number of shared references (shown in *(b)* below). An object with shared references can also have unowned references,
+but not owned ones.
+
+.. image:: ownership-diagram.png
+   :alt: Ownership
+   :width: 1000
+
+In other words, the concept of ownership is having different types of references to an object. There are three different 
+types of references: owned, unowned, and shared.
+Let's use money as an example. If you have $10, that money belongs to you -- you own it. This is the idea of an owned reference.
+You can show this money to anyone else; they can see the money, and talk about it, but they can't do anything with it -- 
+they can't spend it or save it because it's not theirs. This is the idea of an unowned reference; it's a reference to an object,
+but doesn't have as much manipulative power over the object because it doesn't own the object. Now imagine the $10 is in a public pot that anyone can take from. 
+In this case, everyone shares ownership of the money; i.e., you all have shared references to it. Shared references might reflect how you are accustomed to thinking about references.
+
+*Note that ownership ONLY applies to objects; primitive types (like ints, strings, booleans, etc.) do NOT have permissions.*
+
+
+Continuing with money, here is an example of a contract (a ``Wallet``) with an object, a ``Money`` contract, 
+that has one owned reference:
+
+::
+
+   pragma solidity ^0.5.1;
+
+   contract Money {
+   }
+
+   contract Wallet {
+      Money m; // m is owned
+
+      function spendMoney() public {
+         ...
+      }
+   }
+
+In Solidity, we can use comments to indicate ownership. Note that with this code alone, ``m`` is an owned reference that doesn't actually point to any object. If we wanted to create a new object,
+we would do it in a similar way to other object-oriented languages: ``m = new Money()``. Now, ``m`` is an owned reference pointing to a 
+``Money`` object.
+
+- If a reference is the only one that holds ownership, then it is owned.
+- If all references to the object are the same (there is no owner), then each reference is shared.
+- If a reference is NOT the owning one, but there might be another owning reference, then the reference is unowned.
+