Merge pull request #3 from bdpedigo/doc-overhaul

clean up tutorials

README.md

@@ -1,18 +1,18 @@
 # CAVEclient
 
-This repository supplies client side code to interact with microservices
-in the Connectome Annotation Versioning Engine (CAVE).
+CAVE is short for Connectome Annotation Versioning Engine. CAVE is a set of microservices
+that provide a framework for storing and versioning connectomics data and large sets of
+dynamic annotations, metadata, and segmentations. This repository supplies client-side
+code to easily interact with the microservices in CAVE.
 
 ## Installation
 
-Can be installed from pypi
+`CAVEclient` can be installed from PyPI:
 
-`pip install caveclient`
+```bash
+pip install caveclient
+```
 
 ## Documentation
 
 You can find full documentation on readthedocs (https://caveclient.readthedocs.io).
-
-## Usage examples
-
-Tutorial notebook for accessing the FlyWire Connectome dataset: https://github.com/seung-lab/FlyConnectome/blob/main/CAVE%20tutorial.ipynb

docs/index.md

@@ -1,3 +1,26 @@
-{%
-    include-markdown "../README.md"
-%}
+---
+title: CAVEclient
+---
+
+CAVE is short for Connectome Annotation Versioning Engine. CAVE is a set of microservices
+that provide a framework for storing and versioning connectomics data and large sets of
+dynamic annotations, metadata, and segmentations. This repository supplies client-side
+code to easily interact with the microservices in CAVE.
+
+## Documentation Layout
+
+To learn how to install `caveclient`, visit [Installation](./installation.md).
+
+To see hands-on examples of using `caveclient` in a notebook, visit the [Tutorials](./tutorials/index.md).
+
+To see API reference documentation for interacting with a `caveclient.CAVEclient` object (most common),
+visit the [Client API](./client_api/index.md).
+
+To see API reference documentation for interacting with the individual services,
+visit the [Extended API](./extended_api/index.md).
+
+To see a glossary of terms used in the documentation, visit the [Glossary (work in progress)](./glossary.md).
+
+For information about how to contribute to the documentation or the package, visit the [Contributing](./contributing.md) page.
+Feedback on the documentation is welcome! Please [open an issue](https://github.com/{{ config.repo_name }}/issues/new) or
+use the "Edit this page" button at the top right of any page to suggest changes.

docs/installation.md

@@ -1,4 +1,6 @@
-# Installation
+---
+title: Installation
+---
 
 ## Stable release
 

docs/tutorials/annotation.md

@@ -1,4 +1,6 @@
-# AnnotationEngine
+---
+title: Annotation
+---
 
 The AnnotationClient is used to interact with the AnnotationEngine
 service to create tables from existing schema, upload new data, and

docs/tutorials/authentication.md

@@ -1,4 +1,6 @@
-# Authentication
+---
+title: Authentication
+---
 
 Authentication tokens are generally needed for programmatic access to
 our services. The AuthClient handles storing and loading your token or
@@ -9,7 +11,7 @@ token, you probably won't interact with this client very often, however
 it has some convenient features for saving new tokens the first time.
 Let's see if you have a token already. Probably not.
 
-``` python
+```python
 client = CAVEclient()
 auth = client.auth
 print(f"My current token is: {auth.token}")
@@ -28,11 +30,11 @@ By default, the token is saved to
 can come in handy. The following steps will save a token to the default
 location.
 
-``` python
+```python
 auth.get_new_token()
 ```
 
-``` python
+```python
 new_token = 'abcdef1234567890' #This is the text you see after you visit the website.
 auth.save_token(token=new_token)
 print(f"My token is now: {auth.token}")
@@ -55,7 +57,7 @@ when we initialize a new CAVEclient. If we wanted to use a different
 token file, token key, or even directly specify a token we could do so
 here.
 
-``` python
+```python
 client = CAVEclient(datastack_name)
 print(f"Now my basic token is: {client.auth.token}")
 

docs/tutorials/chunkedgraph.md

@@ -1,4 +1,6 @@
-# ChunkedGraph
+---
+title: Chunked Graph
+---
 
 The chunkedgraph is a dynamic oct-tree connected components supervoxel
 graph.

docs/tutorials/framework.md

@@ -1,4 +1,6 @@
-# Introduction
+---
+title: Introduction
+---
 
 ## CAVEclient: one client for all services
 

docs/tutorials/index.md

@@ -1,4 +1,6 @@
-# Getting Started
+---
+title: Getting Started
+---
 
 AnnotationFramework client is a package for simplifying interactions
 with HTML services associated with the CAVE (Connectome Annotation

docs/tutorials/info.md

@@ -1,4 +1,6 @@
-# Info Service
+---
+title: Info Service
+---
 
 A datastack has a number of complex paths to various data sources that
 together comprise a datastack. Rather than hardcode these paths, the
@@ -7,7 +9,7 @@ is also convenient in case data sources change.
 
 An InfoClient is accessed at `client.info`.
 
-``` python
+```python
 client = CAVEclient(datastack_name)
 print(f"This is an info client for {client.info.datastack_name} on {client.info.server_address}")
 ```
@@ -17,14 +19,14 @@ print(f"This is an info client for {client.info.datastack_name} on {client.info.
 All of the information accessible for the datastack can be seen as a
 dict using `get_datastack_info()`.
 
-``` python
+```python
 info.get_datastack_info()
 ```
 
 Individual entries can be found as well. Use tab autocomplete to see the
 various possibilities.
 
-``` python
+```python
 info.graphene_source()
 ```
 
@@ -36,7 +38,7 @@ sometimes one needs to convert between `gs://` style paths to
 in the info client accept a `format_for` argument that can handle this,
 and correctly adapts to graphene vs precomputed data sources.
 
-``` python
+```python
 neuroglancer_style_source = info.image_source(format_for='neuroglancer')
 print(f"With gs-style: { neuroglancer_style_source }")
 

docs/tutorials/l2cache.md

@@ -1,4 +1,6 @@
-# Level 2 Cache
+---
+title: Level 2 Cache
+---
 
 To understand the level 2 cache, you must understand the structure of
 the chunkedgraph so see [the chunkedgraph tutorial](chunkedgraph.md).

docs/tutorials/materialization.md

@@ -1,4 +1,6 @@
-# Materialization
+---
+title: Materialization
+---
 
 The Materialization client allows one to interact with the materialized
 annotation tables, that were posted to the annotation service

docs/tutorials/schemas.md

@@ -1,4 +1,6 @@
-# EMAnnotationSchemas
+---
+title: EM Annotation Schemas
+---
 
 The EMAnnotationSchemas client lets one look up the available schemas
 and how they are defined. This is mostly used for programmatic
@@ -11,7 +13,7 @@ One can get the list of all available schema with the `schema` method.
 Currently, new schema have to be generated on the server side, although
 we aim to have a generic set available to use.
 
-``` python
+```python
 client.schema.schema()
 ```
 
@@ -20,7 +22,7 @@ client.schema.schema()
 The details of each schema can be viewed with the `schema_definition`
 method, formatted as per JSONSchema.
 
-``` python
+```python
 example_schema = client.schema.schema_definition('microns_func_coreg')
 example_schema
 ```
@@ -29,6 +31,6 @@ This is mostly useful for programmatic interaction between services at
 the moment, but can also be used to inspect the expected form of an
 annotation by digging into the format.
 
-``` python
+```python
 example_schema['definitions']['FunctionalCoregistration']
 ```

docs/tutorials/state.md

@@ -1,11 +1,13 @@
-# JSON Neuroglancer State Service
+---
+title: JSON Neuroglancer State Service
+---
 
 We store the JSON description of a Neuroglancer state in a simple
 database at the JSON Service. This is a convenient way to build states
 to distribute to people, or pull states to parse work by individuals.
 The JSON Client is at `client.state`
 
-``` python
+```python
 client.state
 ```
 
@@ -14,7 +16,7 @@ client.state
 JSON states are found simply by their ID, which you get when uploading a
 state. You can download a state with `get_state_json`.
 
-``` python
+```python
 example_id = 4845531975188480
 example_state = client.state.get_state_json(test_id)
 example_state['layers'][0]
@@ -27,16 +29,16 @@ state id is returned by the function. Note that there is no easy way to
 query what you uploaded later, so be VERY CAREFUL with this state id if
 you wish to see it again.
 
-*Note: If you are working with a Neuroglancer Viewer object or similar,
+_Note: If you are working with a Neuroglancer Viewer object or similar,
 in order to upload, use viewer.state.to_json() to generate this
-representation.*
+representation._
 
-``` python
+```python
 example_state['layers'][0]['name'] = 'example_name'
 new_id = client.state.upload_state_json(example_state)
 ```
 
-``` python
+```python
 test_state = client.state.get_state_json(new_id)
 test_state['layers'][0]['name']
 ```
@@ -47,7 +49,7 @@ Once you have a state ID, you want to turn it into a well-formatted
 link. So you don\'t have to remember all the endpoints, we can do this
 from the state client.
 
-``` python
+```python
 ngl_base = 'neuromancer-seung-import.appspot.com'
 client.state.build_neuroglancer_url(new_id, ngl_base)
 ```

mkdocs.yml

@@ -59,12 +59,12 @@ theme:
     # - navigation.path
     - navigation.prune
     # - navigation.sections # toggle to have sections in side nav
-    # - navigation.tabs # toggle to mainly use top nav
+    - navigation.tabs # toggle to mainly use top nav
     - navigation.tabs.sticky
     - content.action.edit
     - content.action.view
     - toc.follow
-    # - toc.integrate # whether to include the toc in the main nav bar to the left
+    - toc.integrate # whether to include the toc in the main nav bar to the left
     - navigation.top
     - search.suggest
     - search.highlight