Merge pull request #156 from alessiamarcolini/typos-docs

Fix typos in tutorials / documentation

Author: rlizzo

AUTHORS.rst

@@ -3,4 +3,4 @@ Authors
 
 * Richard Izzo - [email protected]
 * Luca Antiga - [email protected]
-* Sherin Thomas - [email protected]
+* Sherin Thomas - [email protected]

CHANGELOG.rst

@@ -24,10 +24,12 @@ Improvements
   (`#144 <https://github.com/tensorwerk/hangar-py/pull/144>`__) `@rlizzo <https://github.com/rlizzo>`__
 * Added blosc compression to HDF5 backend by default on PyPi installations.
   (`#146 <https://github.com/tensorwerk/hangar-py/pull/146>`__) `@rlizzo <https://github.com/rlizzo>`__
-* Added CLI options ``commit``, ``checkout``, ``arrayset create``, & ``arrayset remove``
+* Added CLI options ``commit``, ``checkout``, ``arrayset create``, & ``arrayset remove``.
   (`#150 <https://github.com/tensorwerk/hangar-py/pull/150>`__) `@rlizzo <https://github.com/rlizzo>`__
-* Plugin system revamp
+* Plugin system revamp.
   (`#134 <https://github.com/tensorwerk/hangar-py/pull/134>`__) `@hhsecond <https://github.com/hhsecond>`__
+* Documentation Improvements and Typo-Fixes.
+  (`#156 <https://github.com/tensorwerk/hangar-py/pull/156>`__) `@alessiamarcolini <https://github.com/alessiamarcolini>`__
 
 Bug Fixes
 ---------

docs/Tutorial-001.ipynb

@@ -36,15 +36,18 @@
     "\n",
     "Hangar is designed to “just make sense” in every operation you have to perform.\n",
     "As such, there is a single interface which all interaction begins with: the\n",
-    "``Repository`` object.\n",
+    " designed to “just make sense” in every operation you have to perform.\n",
+    "As such, there is a single interface which all interaction begins with: the\n",
+    "[Repository](api.rst#hangar.repository.Repository) object.\n",
     "\n",
-    "Weather a hangar repository exists at the path you specify or not, just tell\n",
+    "Whether a hangar repository exists at the path you specify or not, just tell\n",
     "hangar where it should live!\n",
     "\n",
     "#### Intitializing a repository\n",
     "\n",
-    "The first time you want to work with a new repository, the ``init()`` method\n",
-    "must be called. This is where you provide hangar with your name and email\n",
+    "The first time you want to work with a new repository, the repository \n",
+    "[init()](api.rst#hangar.repository.Repository.init) method\n",
+    "must be called. This is where you provide Hangar with your name and email\n",
     "address (to be used in the commit log), as well as implicitly confirming that\n",
     "you do want to create the underlying data files hangar uses on disk."
    ]
@@ -76,7 +79,7 @@
     "repo = Repository(path='/Users/rick/projects/tensorwerk/hangar/dev/mnist/')\n",
     "\n",
     "# First time a repository is accessed only!\n",
-    "# Note: if you feed a path to the `Repository` which does not contain a pre-iniitlized hangar repo, \n",
+    "# Note: if you feed a path to the `Repository` which does not contain a pre-initialized hangar repo, \n",
     "# when the Repository object is initialized it will let you know that you need to run `init()`\n",
     "\n",
     "repo.init(user_name='Rick Izzo', user_email='[email protected]', remove_old=True)"
@@ -90,18 +93,18 @@
     "\n",
     "A repository can be checked out in two modes:\n",
     "\n",
-    "1. write-enabled: applies all operations to the staging area’s current\n",
+    "1. [write-enabled](api.rst#hangar.checkout.WriterCheckout): applies all operations to the staging area’s current\n",
     "   state. Only one write-enabled checkout can be active at a different time,\n",
     "   must be closed upon last use, or manual intervention will be needed to remove\n",
     "   the writer lock.\n",
     "\n",
-    "2. read-only: checkout a commit or branch to view repository state as it\n",
+    "2. [read-only](api.rst#read-only-checkout): checkout a commit or branch to view repository state as it\n",
     "   existed at that point in time.\n",
     "   \n",
-    "#### Lots of useful information is in the ipython `__repr__`\n",
+    "#### Lots of useful information is in the iPython `__repr__`\n",
     "\n",
     "If you're ever in doubt about what the state of the object your working\n",
-    "on is, just call it's reps, and the most relevant information will be\n",
+    "on is, just call its reps, and the most relevant information will be\n",
     "sent to your screen!"
    ]
   },
@@ -134,10 +137,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### A checkout allows access to `arraysets` and `metadata`\n",
+    "#### A checkout allows access to [arraysets](api.rst#hangar.arrayset.Arraysets) and [metadata](api.rst#hangar.metadata.MetadataWriter)\n",
     "\n",
-    "The `arrayset` and `metadata` attributes of a checkout provide\n",
-    "the interface to working with all of the data on disk!"
+    "The [arraysets](api.rst#hangar.checkout.WriterCheckout.arraysets) and \n",
+    "[metadata](api.rst#hangar.checkout.WriterCheckout.metadata) attributes \n",
+    "of a checkout provide the interface to working with all of the data on disk!"
    ]
   },
   {
@@ -222,74 +226,12 @@
    "source": [
     "#### Before data can be added to a repository, a arrayset must be initialized. \n",
     "\n",
-    "A Arrayset is a named grouping of data samples where each sample shares a\n",
-    "number of similar attributes and array properties. See the docstrings in\n",
-    "`co.arraysets.init_arrayset`:\n",
+    "An \"Arrayset\" is a named grouping of data samples where each sample shares a\n",
+    "number of similar attributes and array properties. \n",
     "\n",
+    "See the docstrings below or in [init_arrayset()](api.rst#hangar.arrayset.Arraysets.init_arrayset)\n",
     "\n",
-    "```\n",
-    "Initializes a arrayset in the repository.\n",
-    "\n",
-    "Arraysets are groups of related data pieces (samples). All samples within\n",
-    "a arrayset have the same data type, and number of dimensions. The size of\n",
-    "each dimension can be either fixed (the default behavior) or variable\n",
-    "per sample.\n",
-    "\n",
-    "For fixed dimension sizes, all samples written to the arrayset must have\n",
-    "the same size that was initially specified upon arrayset initialization.\n",
-    "Variable size arraysets on the other hand, can write samples with\n",
-    "dimensions of any size less than a maximum which is required to be set\n",
-    "upon arrayset creation.\n",
-    "\n",
-    "Parameters\n",
-    "----------\n",
-    "name : str\n",
-    "    The name assigned to this arrayset.\n",
-    "shape : Union[int, Tuple[int]]\n",
-    "    The shape of the data samples which will be written in this arrayset.\n",
-    "    This argument and the `dtype` argument are required if a `prototype`\n",
-    "    is not provided, defaults to None.\n",
-    "dtype : np.dtype\n",
-    "    The datatype of this arrayset. This argument and the `shape` argument\n",
-    "    are required if a `prototype` is not provided., defaults to None.\n",
-    "prototype : np.ndarray\n",
-    "    A sample array of correct datatype and shape which will be used to\n",
-    "    initialize the arrayset storage mechanisms. If this is provided, the\n",
-    "    `shape` and `dtype` arguments must not be set, defaults to None.\n",
-    "named_samples : bool, optional\n",
-    "    If the samples in the arrayset have names associated with them. If set,\n",
-    "    all samples must be provided names, if not, no name will be assigned.\n",
-    "    defaults to True, which means all samples should have names.\n",
-    "variable_shape : bool, optional\n",
-    "    If this is a variable sized arrayset. If true, a the maximum shape is\n",
-    "    set from the provided `shape` or `prototype` argument. Any sample\n",
-    "    added to the arrayset can then have dimension sizes <= to this\n",
-    "    initial specification (so long as they have the same rank as what\n",
-    "    was specified) defaults to False.\n",
-    "backend : DEVELOPER USE ONLY. str, optional, kwarg only\n",
-    "    Backend which should be used to write the arrayset files on disk.\n",
-    "\n",
-    "Returns\n",
-    "-------\n",
-    ":class:`ArraysetDataWriter`\n",
-    "    instance object of the initialized arrayset.\n",
-    "\n",
-    "Raises\n",
-    "------\n",
-    "ValueError\n",
-    "    If provided name contains any non ascii, non alpha-numeric characters.\n",
-    "ValueError\n",
-    "    If required `shape` and `dtype` arguments are not provided in absence of\n",
-    "    `prototype` argument.\n",
-    "ValueError\n",
-    "    If `prototype` argument is not a C contiguous ndarray.\n",
-    "ValueError\n",
-    "    If rank of maximum tensor shape > 31.\n",
-    "ValueError\n",
-    "    If zero sized dimension in `shape` argument\n",
-    "ValueError\n",
-    "    If the specified backend is not valid.\n",
-    "```"
+    ".. automethod:: hangar.arrayset.Arraysets.init_arrayset"
    ]
   },
   {
@@ -333,13 +275,13 @@
     "however, depending on your use case, this may or may not be the most convenient\n",
     "way to access a arrayset.\n",
     "\n",
-    "In general, we have implemented a full ``dict`` mapping interface on top of all\n",
-    "object. To access the ``'mnist_training_images'`` arrayset you can just use a\n",
-    "dict style access like the following (note: if operating in ipython/jupyter, the\n",
+    "In general, we have implemented a full `dict` mapping interface on top of all\n",
+    "objects. To access the `'mnist_training_images'` arrayset you can just use a\n",
+    "dict style access like the following (note: if operating in iPython/Jupyter, the\n",
     "arrayset keys will autocomplete for you).\n",
     "\n",
     "The arrayset objects returned here contain many useful instrospecion methods which\n",
-    "we will review over the rest of the turtorial"
+    "we will review over the rest of the tutorial."
    ]
   },
   {
@@ -411,9 +353,9 @@
    "source": [
     "#### Through the checkout object (arrayset and sample access)\n",
     "\n",
-    "In addition to the standard `co.arraysets` access methods, we have implemented a convenience mapping to `arraysets` and `samples` (ie. data) for both reading and writing from the `checkout` object itself. \n",
+    "In addition to the standard `co.arraysets` access methods, we have implemented a convenience mapping to [arraysets](api.rst#hangar.arrayset.Arraysets) and [samples](api.rst#hangar.arrayset.ArraysetDataWriter) (ie. data) for both reading and writing from the [checkout](api.rst#hangar.checkout.WriterCheckout) object itself. \n",
     "\n",
-    "to get the same arrayset object from the checkout, simply use:"
+    "To get the same arrayset object from the checkout, simply use:"
    ]
   },
   {
@@ -450,7 +392,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Though that works as expected, most use cases will take advantage of adding and reading data from multiple arraysets / samples at a time. This is shown in the next section"
+    "Though that works as expected, most use cases will take advantage of adding and reading data from multiple arraysets / samples at a time. This is shown in the next section."
    ]
   },
   {
@@ -459,8 +401,10 @@
    "source": [
     "#### Adding Data\n",
     "\n",
-    "To add data to a named arrayset, we can use dict-style setting, or the\n",
-    "``.add`` method. Sample keys can be either `str` or `int` type."
+    "To add data to a named arrayset, we can use [dict-style setting](api.rst#hangar.arrayset.ArraysetDataWriter) \n",
+    "(refer to the `__setitem__`, `__getitem__`, and `__delitem__` methods), \n",
+    "or the [add()](api.rst#hangar.arrayset.ArraysetDataWriter.add) method. \n",
+    "Sample keys can be either `str` or `int` type."
    ]
   },
   {
@@ -700,7 +644,8 @@
     "### Performance\n",
     "\n",
     "Once you’ve completed an interactive exploration, be sure to use the context\n",
-    "manager form of the ``.add`` and ``.get`` methods!\n",
+    "manager form of the [add()](api.rst#hangar.arrayset.ArraysetDataWriter.add) and \n",
+    "[get()](api.rst#hangar.arrayset.ArraysetDataWriter.get) methods!\n",
     "\n",
     "In order to make sure that all your data is always safe in Hangar, the backend\n",
     "diligently ensures that all contexts (operations which can somehow interact\n",
@@ -808,7 +753,7 @@
    "source": [
     "### Commiting Changes\n",
     "\n",
-    "Once you have made a set of changes you wan't to commit, just simply call the `commit()` method (and pass in a message)!"
+    "Once you have made a set of changes you want to commit, just simply call the [commit()](api.rst#hangar.checkout.WriterCheckout.commit) method (and pass in a message)!"
    ]
   },
   {
@@ -837,8 +782,7 @@
    "source": [
     "The returned value (`'e11d061dc457b361842801e24cbd119a745089d6'`) is the commit hash of this commit. It\n",
     "may be useful to assign this to a variable and follow this up by creating a\n",
-    "branch from this commit! (Branching to be covered in the next round of\n",
-    "tutorials)"
+    "branch from this commit!"
    ]
   },
   {
@@ -847,18 +791,19 @@
    "source": [
     "#### Don't Forget to Close the Write-Enabled Checkout to Release the Lock!\n",
     "\n",
-    "We mentioned in `Checking out the repo for writing`_ that when a\n",
-    "``write-enabled`` checkout is created, it places a lock on writers until it is\n",
+    "We mentioned in `Checking out the repo for writing` that when a\n",
+    "`write-enabled` checkout is created, it places a lock on writers until it is\n",
     "closed. If for whatever reason the program terminates via a non python `SIGKILL` or fatal\n",
     "interpreter error without closing the\n",
     "write-enabled checkout, this lock will persist (forever technically, but\n",
     "realistically until it is manually freed).\n",
     "\n",
     "Luckily, preventing this issue from occurring is as simple as calling\n",
-    "``close()``!\n",
+    "[close()](api.rst#hangar.checkout.WriterCheckout.close)!\n",
     "\n",
     "If you forget, normal interperter shutdown should trigger an `atexit` hook automatically,\n",
-    "however this behavior should not be relied upon. better to just call ``close()``"
+    "however this behavior should not be relied upon. Is better to just call\n",
+    "[close()](api.rst#hangar.checkout.WriterCheckout.close)."
    ]
   },
   {
@@ -877,15 +822,15 @@
     "#### But if you did forget, and you recieve a `PermissionError` next time you open a checkout\n",
     "\n",
     "```\n",
-    "PermissionError: Cannot aquire the writer lock. Only one instance of\n",
+    "PermissionError: Cannot acquire the writer lock. Only one instance of\n",
     "a writer checkout can be active at a time. If the last checkout of this \n",
     "repository did not properly close, or a crash occured, the lock must be\n",
     "manually freed before another writer can be instantiated.\n",
     "```\n",
     "\n",
     "You can manually free the lock with the following method. However!\n",
     "\n",
-    "This is a dangerous operation, and is one of the only ways where a user can put\n",
+    "This is a dangerous operation, and it's one of the only ways where a user can put\n",
     "data in their repository at risk! If another python process is still holding the\n",
     "lock, do NOT force the release. Kill the process (that's totally fine to do at\n",
     "any time, then force the lock release)."
@@ -1036,4 +981,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}