Add ReadTheDocs documentation

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.8"
+
+python:
+  install:
+    - requirements: requirements.txt
+    - method: pip
+      path: .
+
+sphinx:
+  fail_on_warning: true

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 neuroscout
+Copyright (c) 2022 neuroscout
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,91 +1,28 @@
 # pyNS 🌲
 ![Python package](https://github.com/neuroscout/pyNS/workflows/Python%20package/badge.svg)
 [![codecov](https://codecov.io/gh/neuroscout/pyns/branch/master/graph/badge.svg)](https://codecov.io/gh/neuroscout/pyns)
+[![docs](https://readthedocs.org/projects/pyns/badge/?version=latest)](https://pyns.readthedocs.io/en/latest/)
 
-The Neuroscout API wrapper for Python
+The Neuroscout API wrapper for Python.
 
 ### Overview
-pyNS is a python package to easily interact with the Neuroscout API.
-
-For more API documentation, check out the Swagger API Docs: http://neuroscout.org/swagger-ui/
+pyNS is a python library to easily interact with the Neuroscout API.
+pyNS enables interations with the Neuroscout API in applications such as [neuroscout-cli](https://github.com/neuroscout/neuroscout-cli/), as well as advanced usage of Neuroscout that goes beyond what is possible with the [web application](https://neuroscout.org).
 
 ### Installation
 pyNS is supported in Python 3.4+
 Use `pip` to install it:
 
     pip install pyns
 
-### Quickstart
-For a tutorial on how to build an analysis, see this Jupyter Notebook: https://github.com/neuroscout/pyNS/blob/master/examples/Tutorial.ipynb
-
-We are assuming you already have valid Neuroscout API credentials (and if you dont, sign up at: `neuroscout.org`)
-
-First, instantiate a Neuroscout API Client object:
-
-    from pyns import Neuroscout
-    neuroscout = Neuroscout(username='USERNAME', password='PASSWORD')
-
-With the `neuroscout` instance, you can interact with the API. All of the major routes are linked to the main `neuroscout` object,
-and return `requests` `Response` objects.
-
-For example we can retrieve our user profile:
-
-    >>> neuroscout.user.get()
-    {'email': 'user@example.com',
-     'analyses': [ {'description': 'Does the brain care about language?',
-      'hash_id': 'RZd',
-      'modified_at': '2018-08-09T23:3',
-      'name': 'My new analysis',
-      'status': 'PASSED'}]]}
-
-Or query various endpoints, such as `datasets`:
-
-    >>> neuroscout.datasets.get()
-    [{'description': {'Acknowledgements': '',
-       'Authors': ['Tomoyasu Horikawa', 'Yukiyasu Kamitani'],
-       'DatasetDOI': '',
-       'Funding': '',
-       'HowToAcknowledge': '',
-       'License': '',
-       'Name': 'Generic Object Decoding (fMRI on ImageNet)',
-       'ReferencesAndLinks': ['Horikawa & Kamitani (2017) Generic decoding of seen and imagined objects using hierarchical visual features. Nature Communications volume 8:15037. doi:10.1038/ncomms15037']},
-      'id': 1,
-      'name': 'generic_object_decoding',
-    ...
-      'tasks': [{'id': 8, 'name': 'life'}]}]
-
-For example, we could use this to get the first predictor associated with a dataset:
-
-    >>> first = neuroscout.predictors.get(dataset_id=5)[0]
-    {'description': 'Bounding polygon around face. y coordinate for vertex 1',
-     'extracted_feature': {'created_at': '2018-04-12 00:44:14.868349',
-      'description': 'Bounding polygon around face. y coordinate for vertex 1',
-      'extractor_name': 'GoogleVisionAPIFaceExtractor',
-      'id': 102,
-      'modality': None},
-     'id': 197,
-     'name': 'boundingPoly_vertex1_y',
-     'source': 'extracted'}
-
-
-And get the predictor-events associated with that predictor:
-
-    >>> neuroscout.predictor_events.get(predictor_id=first['id'])[0:2]
-    [{'duration': 9.0,
-      'id': '1050781',
-      'onset': 114.0,
-      'predictor_id': 197,
-      'run_id': 2,
-      'value': '13'},
-     {'duration': 9.0,
-      'id': '1050782',
-      'onset': 114.0,
-      'predictor_id': 197,
-      'run_id': 26,
-      'value': '13'}]
+## Documentation
 
+Full documentation for `pyNS` can be found at [readthedocs] (https://pyns.readthedocs.io/en/latest/).
 
+For API documentation, check out the [Swagger API UI](http://neuroscout.org/swagger-ui/): 
 
+For a tutorial see this [jupyter notebook example](./examples/Tutorial.ipynb).
+You can also follow the Neuroscout Paper's analyses in this interactive [jupyter book](https://neuroscout.github.io/neuroscout-paper/intro.html)
 
 ### Testing
 We use pytest for testing, and betamax to record HTTP requests used in test into cassettes.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+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)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_autosummary/pyns.api.Neuroscout.rst

@@ -0,0 +1,25 @@
+pyns.api.Neuroscout
+===================
+
+.. currentmodule:: pyns.api
+
+.. autoclass:: Neuroscout
+   :members:                                    
+   :show-inheritance:                           
+   :inherited-members:                          
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Neuroscout.__init__
+
+
+
+
+
+

docs/source/_autosummary/pyns.api.rst

@@ -0,0 +1,31 @@
+pyns.api
+========
+
+.. automodule:: pyns.api
+
+
+
+
+
+
+
+
+
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:                                          
+      :template: custom-class-template.rst               
+
+      Neuroscout
+
+
+
+
+
+
+
+
+

docs/source/_autosummary/pyns.endpoints.analysis.Analyses.rst

@@ -0,0 +1,44 @@
+pyns.endpoints.analysis.Analyses
+================================
+
+.. currentmodule:: pyns.endpoints.analysis
+
+.. autoclass:: Analyses
+   :members:                                    
+   :show-inheritance:                           
+   :inherited-members:                          
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Analyses.__init__
+      ~Analyses.clone
+      ~Analyses.compile
+      ~Analyses.create_analysis
+      ~Analyses.delete
+      ~Analyses.fill
+      ~Analyses.generate_report
+      ~Analyses.get_analysis
+      ~Analyses.get_bundle
+      ~Analyses.get_design_matrix
+      ~Analyses.get_full
+      ~Analyses.get_report
+      ~Analyses.get_resources
+      ~Analyses.get_status
+      ~Analyses.get_uploads
+      ~Analyses.load_uploads
+      ~Analyses.plot_report
+      ~Analyses.plot_uploads
+      ~Analyses.put
+      ~Analyses.upload_neurovault
+
+
+
+
+
+

docs/source/_autosummary/pyns.endpoints.analysis.Analysis.rst

@@ -0,0 +1,32 @@
+pyns.endpoints.analysis.Analysis
+================================
+
+.. currentmodule:: pyns.endpoints.analysis
+
+.. autoclass:: Analysis
+   :members:                                    
+   :show-inheritance:                           
+   :inherited-members:                          
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Analysis.__init__
+      ~Analysis.clone
+      ~Analysis.fill
+      ~Analysis.get_full
+      ~Analysis.get_resources
+      ~Analysis.get_status
+      ~Analysis.pull
+      ~Analysis.push
+
+
+
+
+
+

docs/source/_autosummary/pyns.endpoints.analysis.rst

@@ -0,0 +1,32 @@
+pyns.endpoints.analysis
+=======================
+
+.. automodule:: pyns.endpoints.analysis
+
+
+
+
+
+
+
+
+
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:                                          
+      :template: custom-class-template.rst               
+
+      Analyses
+      Analysis
+
+
+
+
+
+
+
+
+

docs/source/_autosummary/pyns.endpoints.base.Base.rst

@@ -0,0 +1,25 @@
+pyns.endpoints.base.Base
+========================
+
+.. currentmodule:: pyns.endpoints.base
+
+.. autoclass:: Base
+   :members:                                    
+   :show-inheritance:                           
+   :inherited-members:                          
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Base.__init__
+
+
+
+
+
+