user_guide.ipynb

{"cells": [{"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "f29adba6-d99b-4cdf-a018-915bae4e31f0"}, "outputs": [], "source": ["# TL;DR Create your first project"]}, {"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "c715d2d3-aaef-47b5-9561-fb55a5e3459e"}, "outputs": [], "source": ["The command below will copy the Halerium project template using cookiecutter, copying the file structure with input slugs to specify certain parameters in the new project template."]}, {"cell_type": "code", "execution_count": 0, "metadata": {"id": "8b6fada4-dc1c-4a14-9b94-ba7656547a2c"}, "outputs": [], "source": ["from cookiecutter.main import cookiecutter\n", "# <halerium id=\"70f3bc0b-4efe-4567-b727-02a8f6ce118e\">\n", "cookiecutter('project_template', output_dir='../')\n", "# </halerium id=\"70f3bc0b-4efe-4567-b727-02a8f6ce118e\">\n"]}, {"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "2b57287a-ea0c-4cee-9176-fd3eb4200b08"}, "outputs": [], "source": ["# Welcome to Halerium!"]}, {"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "db264366-6f12-4c2b-b54f-8688e114d36a"}, "outputs": [], "source": ["## This is a Halerium notebook\r\n", "\r\n", "Halerium notebooks are fully compatible with Jupyter notebooks. Uploaded Jupyter notebooks work in Halerium, downloaded Halerium notebooks work in Jupyter.\r\n", "What makes Halerium notebooks special is that code in them can be linked to cards in Halerium boards."]}, {"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "62aab562-954c-4e15-b601-b9d5d0b84356"}, "outputs": [], "source": ["## Code-card Linking\r\n", "\r\n", "To the right hand side you see the board section. Code blocks (1 or more lines) can be linked to cards on any board.\r\n", "\r\n", "### Create a link\r\n", "To establish a link you can either use the linking button to the bottom right of the notebook section or you can hover the right edge of a code line and use the small linking button that appears then."]}, {"cell_type": "code", "execution_count": 0, "metadata": {"id": "be1e26ff-677c-4c63-8ca1-881008c19469"}, "outputs": [], "source": ["# try to link this line"]}, {"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "db4f3205-f045-4409-9de7-83f9087c2063"}, "outputs": [], "source": ["### Follow a link\r\n", "Once a link is established a decorator appears on the right-hand side of the linked code lines. The decorator has the same color as the linked card. Hovering the decorator opens a preview of the linked card. Clicking the preview centers the linked card in the board section."]}, {"cell_type": "code", "execution_count": 0, "metadata": {"id": "91d97a11-1ca1-46b4-9a58-166f70eb2339"}, "outputs": [], "source": ["# <halerium id=\"250ecf4e-b579-4e9e-b14d-a8c8563329ff\">\n", "# this line is linked\n", "# </halerium id=\"250ecf4e-b579-4e9e-b14d-a8c8563329ff\">\n"]}, {"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "8a519db9-d05c-4c9b-95e7-c004929b92be"}, "outputs": [], "source": ["### Purpose of Links\r\n", "Cards can store information in a more interactive and overview-friendly manner. We therefore advise to utilize boards as the primary information management during a project.\r\n", "\r\n", "Links then connect code and information. There are various scenarios where this is useful, but here are some suggestions:\r\n", " - Link your code to cards containing assumptions or background information that is relevant for it. When the information in the board is updated you can then immediately find the relevant code blocks. Also, if you use that information in multiple notebooks or code blocks the card serves as a single point of truth.\r\n", " - When collecting insights or result in a card, link the code that was used to generate that insight or result. For example, copy a generated plot into a card. If you link the plot generating code lines it becomes much easier for your collaborators (or even future you) to quickly modify the plot by immediately finding the generating code.\r\n", " - Store background reasoning (the why) in cards and link you code to them. This way the background reasoning can be browsed independent of the implementation (increases the overview), but one can immediately jump to the code blocks that depend on it."]}, {"cell_type": "markdown", "execution_count": 0, "metadata": {"id": "d13b9101-ba82-4368-854f-ebed0c581f7c"}, "outputs": [], "source": ["## Notebook crash course\r\n", "\r\n", "A notebook consist of markdown cells and code cells.\r\n", "\r\n", "### add, move, delete cells\r\n", "Below the cell you can find the \"Plus\"-button to add a cell below, the arrow buttons to move the cell and the \"X\"-button to delete the cell. For markdown cells the buttons are only visible if the cell is in edit mode.\r\n", "\r\n", "### markdown cells\r\n", "You can edit markdown cells by double clicking into them. You can render markdown cells by hitting Shift+Enter or clicking the \"Play\"-button to the bottom left of the cell. There you also see the menu to change the cell from markdown to code and vice versa.\r\n", "\r\n", "### code cells\r\n", "You can edit code cells at any time. While editing a code cell you can trigger code autocompletition with the Tab key.\r\n", "To execute the cell hit Shift+Enter or click the \"Play\"-button to the bottom left of the cell.\r\n", "The \"Play\"-button will change to a red cell running indicator until the cell execution is finished.\r\n", "When the execution of the cell is finished the cell's output will appear below. You can delete the output via the \"X\"-button below the output.\r\n", "\r\n", "### global control\r\n", "Above the notebook you have 4 global control buttons to restart the kernel, run all cells, delete all cell outputs and interrupt the kernel."]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 0}