# Collaborative and FAIR workflow part 2: Documentation

This is our collaborative document for today. We will be able to post answers and share links here. This document is synchronized as you type, so that everyone viewing this page sees the same text. We type in Markdown, which will render beautifully on the right side of the page!

## 🗒 Contents

[TOC]

## ⛓ Links
This document: [tinyurl.com/FAIRworkflow-collab]()
Today's slides: [tinyurl.com/FAIRworkflow-part2](https://hackmd.io/@ambjQTu_QASE8UvZFvGL2A/ByRK1BQXj)

## ⬇️ Downloads

## 📆 Agenda
| Time | Topic |
|--:|:---|
|9:00| Recap of last meeting, introduction |
| 9:30 | Literate programming |
| 10:30 | Docstrings & Sphinx |

## 🍦 Ice breaker
What would your power be if you were a superhero?

Yang: super rich (as batman)
Danyang: let it be what to be
Yunfei: can do anything
Barbara: Fast, like the Flash, but then knocking everything over as I go 🙃
Qianqian:super intelligent as Einstein
Enting: travel to everywhere I have seen
Zengjing: let the time go back

## 📜 Instructions & notes

Download the demo example and install the environment we will use today:

git clone https://github.com/bvreede/docsdemo.git
cd docsdemo
conda env create -f environment.yml

Later, you will need to activate the environment:

conda activate docsdemo

If you do not have conda yet:

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh

If you do not have wget:

pip install wget

or use [e.g. this link](https://builtvisible.com/download-your-website-with-wget/) or google it!

### ALTERNATIVE SOLUTION to the environment

pip install jupyterlab
pip install -U sphinx
python3 -m pip install nbsphinx
pip install sphinx-autoapi
pip install sphinx-rtd-theme

conda install -c conda-forge pandoc
pip install --upgrade pandoc

## 🏃🏽 Questions & exercises

### How do you feel about Git & Github?

| Name | Answer |
|:---------|:-------|
| Danyang | useful and interesting|
| Enting |useful and need certain practice with fellows |
| Qianqian |a bit hard to understand and follow the main idea of git|
| Yunfei |make programing more efficient |
| Zengjing |make my work easy |
| Barbara | 🥰 |
| Yang | Make the collaboration much easier. :love_letter:

### Did you do any of the following things in GitHub since our meeting:

#### Open an issue
| Name | Answer |
|:---------|:-------|
| Danyang | √|
| Enting | √ |
| Qianqian |√ |
| Yunfei | ✓|
| Zengjing | ✓|

#### Make a pull request
| Name | Answer |
|:---------|:-------|
| Danyang | ✓|
| Enting | x|
| Qianqian | ×|
| Yunfei | ✓|
| Zengjing | ✓|

#### Push code
| Name | Answer |
|:---------|:-------|
| Danyang | ✓|
| Enting | x |
| Qianqian | ×|
| Yunfei | ✓|
| Zengjing | |

#### Review someone else's code
| Name | Answer |
|:---------|:-------|
| Danyang | x|
| Enting | x|
| Qianqian | ×|
| Yunfei | ×|
| Zengjing | ✓|

#### Received code review, and used it to discuss/improve the code
| Name | Answer |
|:---------|:-------|
| Danyang | ✓|
| Enting ||
| Qianqian | ×|
| Yunfei | |
| Zengjing | |

#### Anything else that you did/learned/have questions about?

### Write a docstring

def add(a, b):
    """Add two numbers together
    
    This function is a wrapper over the ``+``
    symbol. It should only take integers,
    though it will probably be ok with floats,
    and even strings!

    Args:
        a (int): The first number
        b (int): The second number

    Returns:
        int: The sum of both numbers
    """
    return a + b


# Enting
def subtract(a, b):
    """Subtract two numbers
    
    Args:
        a (int): The first number
        b (int): The second number

    Returns:
        int: The difference between two numbers
    """
    return a - b



# Danyang
def multiply(a, b):
    """multiply two numbers together

    Args:
        a (int): The first number
        b (int): The second number

    Returns:
        int: The multiplication of both numbers
    """
    return a * b

# Qianqian
def divide(a, b):
    """divide two numbers

    Args:
        a (int): The first number
        b (int): The second number

    Returns:
        float: The quotient of the first number dividing the second number
    """
    return a / b

# Yunfei
def power(a, b):
    """Calculate a to the power of b

    Args:
        a (int): The first number
        b (int): The second number

    Returns:
        int: The Power a of b
    """
    return a ** b

## 📚 Resources
- [Autodocstring, a VSCode extension](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring)