From 00bfe3c7c8ce383a13f2cb880a0d32ab7c2c24af Mon Sep 17 00:00:00 2001 From: Ben Pedigo Date: Fri, 19 Jan 2024 09:55:48 -0800 Subject: [PATCH] clean up tutorials --- README.md | 16 ++++++++-------- docs/index.md | 29 ++++++++++++++++++++++++++--- docs/installation.md | 4 +++- docs/tutorials/annotation.md | 4 +++- docs/tutorials/authentication.md | 12 +++++++----- docs/tutorials/chunkedgraph.md | 4 +++- docs/tutorials/framework.md | 4 +++- docs/tutorials/index.md | 4 +++- docs/tutorials/info.md | 12 +++++++----- docs/tutorials/l2cache.md | 4 +++- docs/tutorials/materialization.md | 4 +++- docs/tutorials/schemas.md | 10 ++++++---- docs/tutorials/state.md | 18 ++++++++++-------- mkdocs.yml | 4 ++-- 14 files changed, 87 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index b674b5b3..9ce3736b 100644 --- a/README.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index 925533ac..01c85106 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/installation.md b/docs/installation.md index 1a133ea2..5a9caa20 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,4 +1,6 @@ -# Installation +--- +title: Installation +--- ## Stable release diff --git a/docs/tutorials/annotation.md b/docs/tutorials/annotation.md index a74780b4..24f98426 100644 --- a/docs/tutorials/annotation.md +++ b/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 diff --git a/docs/tutorials/authentication.md b/docs/tutorials/authentication.md index 68decb7b..e48ca0b3 100644 --- a/docs/tutorials/authentication.md +++ b/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}") diff --git a/docs/tutorials/chunkedgraph.md b/docs/tutorials/chunkedgraph.md index 14eada55..4f1c8b99 100644 --- a/docs/tutorials/chunkedgraph.md +++ b/docs/tutorials/chunkedgraph.md @@ -1,4 +1,6 @@ -# ChunkedGraph +--- +title: Chunked Graph +--- The chunkedgraph is a dynamic oct-tree connected components supervoxel graph. diff --git a/docs/tutorials/framework.md b/docs/tutorials/framework.md index d19f9743..34e2e9f2 100644 --- a/docs/tutorials/framework.md +++ b/docs/tutorials/framework.md @@ -1,4 +1,6 @@ -# Introduction +--- +title: Introduction +--- ## CAVEclient: one client for all services diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index ddb4ca75..19b7b317 100644 --- a/docs/tutorials/index.md +++ b/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 diff --git a/docs/tutorials/info.md b/docs/tutorials/info.md index f7e34350..7bfcd222 100644 --- a/docs/tutorials/info.md +++ b/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 }") diff --git a/docs/tutorials/l2cache.md b/docs/tutorials/l2cache.md index a183579d..614a265f 100644 --- a/docs/tutorials/l2cache.md +++ b/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). diff --git a/docs/tutorials/materialization.md b/docs/tutorials/materialization.md index 380aa811..de5ecefb 100644 --- a/docs/tutorials/materialization.md +++ b/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 diff --git a/docs/tutorials/schemas.md b/docs/tutorials/schemas.md index 65a703bb..b13d21c7 100644 --- a/docs/tutorials/schemas.md +++ b/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'] ``` diff --git a/docs/tutorials/state.md b/docs/tutorials/state.md index c329cb1d..7434e2ce 100644 --- a/docs/tutorials/state.md +++ b/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) ``` diff --git a/mkdocs.yml b/mkdocs.yml index de424df2..3cc4950b 100644 --- a/mkdocs.yml +++ b/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