Creating a Tutorial or Example

In Besca we strive to make single-cell sequencing analysis easily accessible to a wide user base. For this it is essential that all of Besca's functionalities are well documented. Especially useful are Tutorials and Examples which demonstrate Besca's capabilities. So whenever you create a cool new feature for besca please at minimum create a working example. If it is a more complex tool consider creating a specialized tutorial which introduces users to the tools functionality and implementation.

Creating an Example

Please also refer to documenting functions

Adding an Example to the Sphynx gallery

Examples are displayed using sphinx gallery. The scripts used to generate examples for the sphinx-gallery in the documentation are an exception since they belong to the documentation but are also executed using the besca package. Within the general package structure they are located within ./besca/examples/gallery_examples. The gallery examples are again subdivided into four categories each of which have their own folder within the larger package structure. To mark these folders as belonging to the gallery they each contain a README.txt file which contains all of the text that should be rendered in the documentation under that specific subsection.

examples
├── gallery_examples │ ├── README.txt
│ ├── plotting
│ │ ├── README.txt
│ │ └── ... (examples as .py files)
│ ├── preprocessing
│ │ ├── README.txt
│ │ └── ... (examples as .py files)
│ ├── tools
│ │ ├── README.txt
│ │ └── ... (examples as .py files)
│ ├── workflows
│ │ ├── README.txt
│ │ └── ... (examples as .py files)
│ └── figures_testing
│ └── ... (figures generated by the examples within the gallery)
└── ... other example scripts not intended for gallery

Adding a Tutorial

Tutorials are added in the form of jupyer notebooks with the extension .ipynb. They are executed upon compiling the new documentation so please ensure that they only contain besca internal functions and do not rely on any external data or materials.

1. relocate your completed tutorial to the folder './besca/docs/source/tutorials'
2. add the tutorial to the table of contents in the tutorials.rst file so that users can navigate to it from the main besca documentation.
3. (optional) if desired you can add a restructured text section to the tutorials page which briefly describes your tutorial. You can add links to the tutorial in the form :doc:labels <tutorials/tutorial_name>``.