Merge pull request #361 from int-brain-lab/docs

Docs

.github/workflows/build_docs.yml

@@ -56,6 +56,7 @@ jobs:
  - name: Install docs requirements
  run: |
  sudo apt-get install -y pandoc
+ export TQDM_DISABLE=1
  pip install -r docs_gh_pages/requirements-docs.txt
  pip install -e ../ibllib-repo
  pip install jupyter

docs_gh_pages/README.md

@@ -23,24 +23,76 @@ e.g `docs_coronal_slice.py` or `docs_get_LFP_data.ipynb`. Each example/ tutorial
 description of the content. Please refer to the templates in the [templates folder](./templates) for examples of 
 how to layout the title and description in order for it to be correctly rendered and displayed on the website. 
 
-Once you have created the example/ tutorial you should link to the file in either `05_tutorials.rst` or `06_examples.rst`.
+Once you have created the example/ tutorial you should link to the file in the appropriate `.rst` file: `index.rst`, `06_examples.rst`
+, `atlas_examples.rst` etc...
 The link should be made by adding in the following line `notebooks_external\name_of_example_without_extension`, e.g
 `notebooks_external\docs_coronal_slice`
 
 `notebooks_external\docs_get_LFP_data`
 
 An example implementation can be seen in the `06_examples.rst` file
 
+### Tips to create and edit example notebooks
+
+#### Hide a cell in the documentation
+In the cell metadata, add the key `nbsphinx` with the value `hidden` to hide the cell in the documentation.
+
+```json
+{
+ "nbsphinx": "hidden",
+ "trusted": false
+}
+```
+
+#### Prevent execution of a cell in the build documentation
+Let's say an example is using too large of a dataset. One cell can be disabled by adding the following key to the to cell metadata.
+
+```json
+{
+ "ibl_execute": false
+}
+```
+
+#### Prevent execution of the whole notebook in the build documentation
+If the full notebook is to be skipped, you can also set the `ibl_execute` flag to `false` in the notebook metadata.
+
+#### Disable logging and tqdm output:
+To have a clean output in the documentation, it is recommended to disable the logging and tqdm output in the example by adding a hidden cell at the top of the notebook.
+(make sure the cell metadata contains the key `nbsphinx` with the value `hidden` as specified above)
+
+```python
+# Turn off logging and disable tqdm this is a hidden cell on docs page
+import logging
+import os
+
+logger = logging.getLogger('ibllib')
+logger.setLevel(logging.CRITICAL)
+
+os.environ["TQDM_DISABLE"] = "1"
+```
+
 ## Making documentation using github actions
 Two github actions workflows have been made available to automate the building and the deployment of the docs. These are located in the int-brain-lab/iblenv repository and can be accessed under the actions tab
 
 ### Developing docs
-When testing and developing docs use the [Build docs workflow](https://github.com/int-brain-lab/iblenv/actions/workflows/build_docs.yml). Any changes to the documentation must be made on the `docs` branch of either ibllib and iblenv. At the moment the workflow requires the docs branch to exist in both repos (TODO if it doesn't exist make github action fallback to master). To run the workflow click on the `run_workflow` button in the top left corner and choose the branch you want to launch it from (this should normally be docs). After the docs build has completed succesfully your documentation will appear at this site http://testdocs.internationalbrainlab.org.s3-website-us-east-1.amazonaws.com
+
+Steps:
+- create documentation branches called `docs` on the `ibllib` and `iblenv` repositories. The workflow will only run if the branch exists in both repos (TODO if it doesn't exist make github action fallback to master)
+- add your changes to the documentation
+- run the [Build docs workflow](https://github.com/int-brain-lab/iblenv/actions/workflows/build_docs.yml). To run the workflow click on the `run_workflow` button in the top left corner and choose the branch you want to launch it from (this should normally be docs).
+
+After the docs build has completed succesfully your documentation will appear at this site http://testdocs.internationalbrainlab.org.s3-website-us-east-1.amazonaws.com
+
 
 ### Deploying docs
 **WARNING: Do not run this workflow unless you have run the build docs workflow above and checked that the documentation is correct**
 
-Once you are happy with the documentation, the docs branch/es you have been working on need to be merged into master in iblenv, and into develop in ibllib. Once those have been merged you should run the [Deploy docs workflow](https://github.com/int-brain-lab/iblenv/actions/workflows/deploy_docs.yml). To run the workflow click on the `run_workflow` button in the top left corner and choose the branch you want to launch it from (this should be master). The new docs will then be deployed to the main documnetation website https://int-brain-lab.github.io/iblenv/
+Steps:
+- merge the `docs` branch into `master` on the `iblenv` repository
+- merge the `docs` branch into `develop` on the `ibllib` repository
+- run the [Deploy docs workflow](https://github.com/int-brain-lab/iblenv/actions/workflows/deploy_docs.yml). To run the workflow click on the `run_workflow` button in the top left corner and choose the branch you want to launch it from (this should be master).
+
+The new docs will then be deployed to the main documnetation website https://int-brain-lab.github.io/iblenv/
 
 
 ## Making documentation locally

docs_gh_pages/atlas_examples.rst

@@ -1,8 +1,17 @@
 Atlas Examples
 ==============
 
+We present a set of hands-on examples to illustrate how to manipulate and visualize hierarchical brain atlas ontologies.
+The full package documentation can be found `here <https://int-brain-lab.github.io/iblenv/_autosummary/iblatlas.html#module-iblatlas>`_
+
+Anatomical Atlases
+******************
+
 Below is a list of examples using the ibllib.atlas module
 
+The Allen Mouse Brain Common Coordinate Framework: A 3D Reference Atlas. Cell. 181(4):936-953.e20. doi: 10.1016/j.cell.2020.04.007.
+https://www.sciencedirect.com/science/article/pii/S0092867420304025
+
 .. toctree::
  :maxdepth: 1
 
@@ -13,3 +22,17 @@ Below is a list of examples using the ibllib.atlas module
  notebooks_external/atlas_circular_pyramidal_flatmap
  notebooks_external/atlas_plotting_points_on_slice
  notebooks_external/atlas_swanson_flatmap
+
+
+Gene expression
+***************
+
+.. toctree::
+ :maxdepth: 1
+
+ notebooks_external/atlas_genomics_load_agea
+
+Ng, L., Bernard, A., Lau, C. et al. An anatomic gene expression atlas of the adult mouse brain. Nat Neurosci 12, 356–362 (2009). https://doi.org/10.1038/nn.2281
+https://www.nature.com/articles/nn.2281
+
+Lein, E.S. et al. (2007). Genome-wide atlas of gene expression in the adult mouse brain, Nature 445: 168-176. https://doi:10.1038/nature05453

docs_gh_pages/make_script.py

@@ -4,10 +4,13 @@
 import argparse
 import subprocess
 from pathlib import Path
-import logging
+
+from iblutil.util import setup_logger
 from scripts.execute_notebooks import process_notebooks
 
-_logger = logging.getLogger('ibllib')
+os.environ["TQDM_DISABLE"] = "1"
+_logger = setup_logger(name='íbllib', level=20)
+
 root = Path.cwd()
 scripts_path = root.joinpath('scripts')
 
@@ -22,6 +25,7 @@
 # external_file_patterns = ['docs', 'loading', 'atlas', 'docs', 'quickstart']
 external_file_patterns = ['loading', 'atlas', 'data', 'data', 'docs_wheel', 'quickstart']
 
+
 def make_documentation(execute, force, documentation, clean, specific, github, message, pre_clean):
 
  # Clean up any nblink files
@@ -175,4 +179,4 @@ def make_documentation(execute, force, documentation, clean, specific, github, m
  args = parser.parse_args()
  make_documentation(execute=args.execute, force=args.force, documentation=args.documentation,
  clean=args.cleanup, specific=args.specific, github=args.github,
- message=args.message, pre_clean=args.preclean)
+ message=args.message, pre_clean=args.preclean)