Write/connect VBN documentation notebooks

danielsf commented 2 years ago

Tasks

[x] Write basic data access notebook for VBN (basically copied from the one we wrote for VBO)
[x] Get example data analysis notebooks from scientists
[x] Incorporate scientist notebooks into doc_templates/examples/example_root/nb
[x] write a visual_behavior_neuropixels.rst document and link it to all of the notebooks
[x] link visual_behavior_neuropixels.rst to index.rst
[x] verify that the readthedocs page will automatically get updated with all of the VBN content once we issue our post-VBN release of the SDK

All of this work is going to take place in the doc_templates/ directory of the SDK

danielsf commented 2 years ago

Since it is becoming more likely that this will get merged after I go on leave, I have started this work in this branch

https://github.com/AllenInstitute/AllenSDK/tree/ticket/2470/vbn/documentation

danielsf commented 2 years ago

In the event that I need to go on leave before this work gets closed, I'm going to document what I've learned about publishing our documentation in readthedocs and (more importantly) how to see a dev-branch based set of documents.

readthedocs automatically builds a copy of our documentation whenever a commit is pushed to a pull request. To see that build, go here

https://readthedocs.org/projects/allensdk/

You will need to sign in to readthedocs as AllenInstituteCI. Credentials are in our 1Password shared vault. Click on the Builds button. You should see a list of recent builds. Look for one that is built off of your PR (for instance, PR #2471 in this case)

To see the documents built for the PR click on one of those builds. You should see a View docs hyper link on the right. Click on that to load the documents.

Clicking on the View docs hyperlink will take you to the landing page for our documentation. This is where things get a little tricky. For reasons that I do not understand, the .rst files from which we are building our documents all include hard-coded links to the latest copy of the documents, see for instance this block from the main copy of index.rst

.. list-table:: 
   :widths: 25 50 50 25
   :header-rows: 1

   * - Behavior
     - Modality
     - Resource
     - Initial Release
   * - Passive
     - Optical physiology
     - `Visual Coding - Optical Physiology <https://allensdk.readthedocs.io/en/latest/brain_observatory.html>`_

This means that, if you were naively to click on the hyper link in the branch copy of the documentation, it would take you to the latest copy of the Visual Coding - Optical Physiology page not the copy of Visual Coding - Optical Physiology associated with the branch whose docs you are looking at. In this commit

https://github.com/AllenInstitute/AllenSDK/pull/2471/commits/2442f3c7500123aa8797f16414f6e61131067b65

I change that behavior so that branch-built versions of the docs stay internally linked. Now, if you click on that link, you will go to the in-branch version of that page.

You can tell, both because the PR number appears in the URL, and the pink warning bar at the top of the page. I do not know if there was a terribly good reason we were forcing all of our hyperlinks to point to latest or not. This is probably something to be aware of before merging PR #2471. In any event, changing the hyperlinks the way I reference above is going to be necessary in order to create a self-consistent set of docs based off of a PR that we can show the scientists before merging to main.

Similarly, the example notebooks we have written link to each other but the links are hard-coded to point to latest. This commit

https://github.com/AllenInstitute/AllenSDK/pull/2471/commits/98803a4629694546716572a77c9f8942f246ddec

shows how to get a relative link the notebook so that you can click around the docs and stay in the PR you mean to be inspecting.

Again: check the URLs of any notebooks you load to make sure you are where you mean to be

as opposed to

which I got to by clicking links off of the PR 2469 build in readthedocs. Note that the first two include a reference to PR 2471 in the URL, while the last one is explicitly the latest copy of the notebook.

Beyond that (again, assuming I am unable to see this work through): in #2471 I have created a rough-draft VBN data access notebook by shamelessly copying the VBO data access notebook and changing all of the relevant import statements. I have also incorporated the quality-metrics notebook that Shawn gave me. I created a link from index.rst to a VBN landing .rst page. Right now that page is just a copy of what we did for VBO. It will need to be changed to contain links and documentation appropriate for VBN.

danielsf commented 2 years ago

It occurs to me that the links within notebooks may all be hard-coded to point to latest so that, if someone download's a notebook, they still get a working link to other notebooks. I'm not sure how to deal with that. Probably the answer is to use relative links while we are still developing the documentation and getting sign-off from the scientists, but to change all of those links to absolute links to latest before publishing the documents to main...?

danielsf commented 2 years ago

According to this page there is also an easy way to build the docs locally.

Running sphinx-build -a . /Users/scott.daniel/Pika/garage/doc_test/ from inside AllenSDK/doc_templates/ put a complete set of html files in /Users/scott.daniel/Pika/garage/doc_test/ (open index.html to get to the landing page for our docs). It also wrote a bunch of unwanted html files in AllenSDK/doc_templates/, but maybe there's a clean-up flag I'm not seeing.

AllenInstitute / AllenSDK

Write/connect VBN documentation notebooks #2470