Update doc for next version bump

CHANGELOG.rst

@@ -6,3 +6,11 @@ Changelog
 -------------------
 
 * Initial release (work in progress).
+
+
+0.0.2 (2018/10/18)
+-------------------
+
+* Completed first documentation pass.
+* Fixed travis/rtfd builds.
+* Fixed device mapping/loading issues.

CONTRIBUTING.rst

@@ -40,23 +40,23 @@ To set up `thelper` for local development:
    (look for the "Fork" button).
 2. Clone your fork locally::
 
-    git clone git@github.com:your_name_here/thelper.git
+  $ git clone git@github.com:your_name_here/thelper.git
 
 3. Create a branch for local development::
 
-    git checkout -b name-of-your-bugfix-or-feature
+  $ git checkout -b name-of-your-bugfix-or-feature
 
    Now you can make your changes locally.
 
-4. When you're done making changes, run all the checks and doc builder with `tox <https://tox.readthedocs.io/en/latest/install.html>`_ one command::
+4. When you're done making changes, run all the checks and doc builder with `tox <https://tox.readthedocs.io/en/latest/install.html>`_ via::
 
-    tox
+  $ make test-all
 
 5. Commit your changes and push your branch to GitHub::
 
-    git add .
-    git commit -m "Your detailed description of your changes."
-    git push origin name-of-your-bugfix-or-feature
+  $ git add .
+  $ git commit -m "Your detailed description of your changes."
+  $ git push origin name-of-your-bugfix-or-feature
 
 6. Submit a pull request through the GitHub website.
 
@@ -67,7 +67,7 @@ If you need some code review or feedback while you're developing the code just m
 
 For merging, you should:
 
-1. Include passing tests (run ``tox``) [1]_.
+1. Make sure all tests are passing (run ``make test-all``) [1]_.
 2. Update documentation when there's new API, functionality etc.
 3. Add a note to ``CHANGELOG.rst`` about the changes.
 4. Add yourself to ``AUTHORS.rst``.
@@ -76,14 +76,3 @@ For merging, you should:
        `run the tests <https://travis-ci.org/plstcharles/thelper/pull_requests>`_ for each change you add in the pull request.
 
        It will be slower though ...
-
-Tips
-----
-
-To run a subset of tests::
-
-    tox -e envname -- pytest -k test_myfeature
-
-To run all the test environments in *parallel* (you need to ``pip install detox``)::
-
-    detox

DOCUMENTATION.rst

@@ -0,0 +1,12 @@
+=============
+Documentation
+=============
+
+The sphinx documentation is generated automatically via `readthedocs.io <https://readthedocs.org/projects/thelper/>`_, but it might
+still be incomplete due to buggy apidoc usage/platform limitations. To build it yourself, use the makefile::
+
+  $ cd <THELPER_ROOT>
+  $ make docs
+
+The HTML documentation should then be generated inside ``<THELPER_ROOT>/docs/build/html``. To browse it, simply open the
+``index.html`` file there.

INSTALL.rst

@@ -12,7 +12,7 @@ the thelper framework and all its dependencies. In your terminal, simply enter::
   $ make install
 
 If you already have conda installed somewhere, you can force the Makefile to use it for the installation of the
-new environment by setting the :code:`CONDA_HOME` variable before calling make::
+new environment by setting the ``CONDA_HOME`` variable before calling make::
 
   $ export CONDA_HOME=/some/path/to/miniconda3
   $ cd <THELPER_ROOT>
@@ -31,8 +31,9 @@ Other systems
 -------------
 
 If you cannot use the Makefile, you will have to install the dependencies yourself. These dependencies are listed in
-the `requirements file <requirements.txt>`_, and can be installed using the conda environment configuration
-file provided `here <conda-env.yml>`_. For the latter case, call the following from your terminal::
+the `requirements file <https://github.com/plstcharles/thelper/blob/master/requirements.txt>`_, and can also be installed
+using the conda environment configuration file provided `here <https://github.com/plstcharles/thelper/blob/master/conda-env.yml>`_.
+For the latter case, call the following from your terminal::
 
   $ conda env create --file <THELPER_ROOT>/conda-env.yml -n thelper
 
@@ -61,10 +62,3 @@ that all dependencies can be loaded at runtime::
     >>> import thelper
     >>> print(thelper.__version__)
     x.y.z
-
-
-User guide
-----------
-
-For now, we offer some high-level guidelines in the `thelper_usage.txt <thelper_usage.txt>`_ file contained in this
-repository. More documentation will soon be added!

README.rst

@@ -56,39 +56,9 @@ This package provides a training framework and CLI for PyTorch-based machine lea
 under the `Apache Software License version 2.0 <https://tldrlegal.com/license/apache-license-2.0-(apache-2.0)>`_ built by researchers
 and developers from the Centre de Recherche Informatique de Montréal / Computer Research Institute of Montreal (CRIM).
 
-For installation and usage instructions, refer to the `installation guide <INSTALL.rst>`_.
-
-
-.. doc/dev instructions below not ready for live version (WiP)
-
-   Documentation
-   =============
-
-   https://thelper.readthedocs.io/
-
-   Development
-   ===========
-
-   To run the all tests run::
-
-       tox
-
-   Note, to combine the coverage data from all the tox environments run:
-
-   .. list-table::
-       :widths: 10 90
-       :stub-columns: 1
-
-       - - Windows
-         - ::
-
-               set PYTEST_ADDOPTS=--cov-append
-               tox
-
-       - - Other
-         - ::
-
-               PYTEST_ADDOPTS=--cov-append tox
+For installation instructions, refer to the `installation guide <https://github.com/plstcharles/thelper/blob/master/INSTALL.rst>`_. For
+usage instructions, refer to the `user guide <https://github.com/plstcharles/thelper/blob/master/thelper_usage.txt>`_. Information about
+the auto-generated documentation is available `here <https://github.com/plstcharles/thelper/blob/master/DOCUMENTATION.rst>`_.
 
 =====
 Notes

docs/src/documentation.rst

@@ -0,0 +1 @@
+.. include:: ../../DOCUMENTATION.rst

docs/src/index.rst

@@ -7,6 +7,7 @@ Contents
 
    readme
    installation
+   documentation
    usage
    modules
    contributing
@@ -16,7 +17,4 @@ Contents
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-

docs/src/usage.rst

@@ -2,6 +2,5 @@
 Usage
 =====
 
-To use ``thelper`` in a project::
-
-	import thelper
+For now, we offer some high-level guidelines in the `thelper_usage.txt <https://github.com/plstcharles/thelper/blob/master/thelper_usage.txt>`_
+file. More examples/tutorials will soon be added!