Merge pull request #490 from sciris/add-readmes

Add readmes

docs/README.md

@@ -0,0 +1,20 @@
+# Sciris docs
+
+## Tutorials
+
+Please see the `tutorials` subfolder.
+
+## Everything else
+
+This folder includes source code for building the docs. Users are unlikely to need to do this themselves. Instead, view the Sciris docs at http://docs.sciris.org.
+
+To build the docs, follow these steps:
+
+1.  Make sure dependencies are installed::
+    ```
+    pip install -r requirements.txt
+    ```
+
+2.  Make the documents; there are many build options. In most cases, running `./build_docs` (to rerun the tutorials; takes a few minutes) is best. Alternatively, you can call `make html` directly.
+
+3.  The built documents will be in `./_build/html`.

docs/tutorials/README.md

@@ -0,0 +1,3 @@
+# Tutorials
+
+These tutorials walk through how to use Sciris. They are available via http://docs.sciris.org. To run locally, start a Jupyter environment (either `jupyter lab` or `jupyter notebook`) in this folder (`docs/tutorials`).

sciris/README.md

@@ -0,0 +1,3 @@
+# Sciris main folder
+
+This folder contains all of Sciris' source code. See [the docs](http://docs.sciris.org) for more information.

sciris/_extras/README.rst → sciris/_extras/README.md

@@ -1,8 +1,7 @@
-======
-Extras
-======
+# Extras
 
 This folder contains two files:
+
 - ``ansicolors.py`` is a copy of https://github.com/jonathaneunice/colors/, to avoid install issues on conda;
 - ``legacy.py`` is a graveyard for old (but conceivably, if improbably, still useful) Sciris functions.