Hint for writing tutorials with Markdown syntax#

Comment#

In case you need, you can comment a line with

% This is a comment.

References#

Internal link#

If you need to reference a header/figure/code in your document, first create a target in your document by using the following:

(target)=
#### Header example

Header example#

Then reference it with:

Link	Code
Header example	{ref}`target`
Alternative text	{ref}`Alternative text <target>`
Header example	`[](target)`
Alternative text	`[Alternative text](target)`

For figures and code, you can also use the configurable options.

HTML Link#

Link	Code
https://doc.dataiku.com	`<https://doc.dataiku.com>`
product documentation	`[product documentation](https://doc.dataiku.com)`

Link to an existing doc#

Link	Code
Getting started	{doc}`/getting-started/index`
With alternative text	{doc}`With alternative text </getting-started/index>`

Link to Refdoc#

Link	Code
Python recipes	{doc}`refdoc:code_recipes/python`
here	{doc}`here <refdoc:code_recipes/python>`

Figure and Code#

If you want to number your figure or code, you need to do it manually. We do not use automatic numbering as automatic numbering will be for the whole documentation without resetting the numbering by the document.

Figures#

A simple figure without any configuration is obtained by using the following: ![dku-diagram.png](/getting-started/intro-value/assets/dku-diagram.png){.image-popup}
more advanced figure with configuration options

Figure 1: Here goes the caption#

This is obtained by using the following:
```
      ```{figure} /getting-started/intro-value/assets/dku-diagram.png
      :name: contributing_template_md_label
      :width: 100px
  
      Figure 1: Here goes the caption
      ```
```
then you can refer to the figure by using the :name: defined in the figure block, like an internal link.

Code#

Inline-code: example = True

Syntax highlighting for long code

import dataiku

client = dataiku.api_client()

      ```python
      import dataiku

      client = dataiku.api_client()
      ```

Configurable code block

Code 1 – Code sample#

import dataiku

client = dataiku.api_client()

This code sample can be referenced with the internal link reference syntax and is obtained with the following:

      ```{code-block} python
      :name: contributing_template_md_code_sample
      :caption: Code 1 -- Code sample
      :linenos:
      :emphasize-lines: 1,3

      import dataiku

      client = dataiku.api_client()
      ```

You can also use the literalinclude code syntax

      ```{literalinclude} /tutorials/devtools/project-libs-unit-tests/prepare.py
      :language: python
      :caption: Code 2 -- Included code
      :name: contributing_template_md_code_included
      :emphasize-lines: 1-7
      :linenos:
      ```

Code 2 – Included code#

import pandas as pd
from datetime import datetime

# Useful to de-normalize tenperature.
# Check https://archive.ics.uci.edu/ml/datasets/bike+sharing+dataset for more details
TEMP_MIN_C = -8.0
TEMP_MAX_C = 39.0

def with_temp_fahrenheit(df: pd.DataFrame, temp_col: str) -> pd.DataFrame:
    """
    Denormalize temperature then convert it to Fahrenheit degrees.

    Args:
        df (pd.DataFrame): Input pandas DataFrame to chain on.
        temp_col (str): DataFrame column name for normalized temperature.
    
    Returns:
        A pandas DataFrame with a new column called "temp_F" containing
        de-normalized temperature in Fahrenheit degrees.
    """
    df["temp_F"] = 1.8 * (TEMP_MIN_C+df[temp_col].astype(float) * (TEMP_MAX_C-TEMP_MIN_C)) + 32.0
    return df

def with_datetime(df: pd.DataFrame,
                  date_col: str,
                  hour_col: str) -> str:
    """
    Create a proper datetime column.

    Args:
        df (pd.DataFrame): Input pandas DataFrame to chain on.
        date_col (str) : column name in df containing date value (e.g. 2023-04-29)
        hour_col (str): column name in df containing hour value (e.g. 21)
    
    Returns:
        A pandas DataFrame with a new column called "datetime" containing
        date + hour information in ISO8601 format.
    """

    df["datetime"] = (df[date_col] + ' ' + df[hour_col].astype(str)) \
        .apply(lambda x: datetime.strptime(x, "%Y-%m-%d %H")) \
        .apply(datetime.isoformat)
    return df

You can also just include a function

Code 3 – Included code (partial inclusion)#

def with_temp_fahrenheit(df: pd.DataFrame, temp_col: str) -> pd.DataFrame:
    """
    Denormalize temperature then convert it to Fahrenheit degrees.

    Args:
        df (pd.DataFrame): Input pandas DataFrame to chain on.
        temp_col (str): DataFrame column name for normalized temperature.
    
    Returns:
        A pandas DataFrame with a new column called "temp_F" containing
        de-normalized temperature in Fahrenheit degrees.
    """
    df["temp_F"] = 1.8 * (TEMP_MIN_C+df[temp_col].astype(float) * (TEMP_MAX_C-TEMP_MIN_C)) + 32.0
    return df

        ```{literalinclude} /tutorials/devtools/project-libs-unit-tests/prepare.py
        :language: python
        :caption: Code 3 -- Included code (partial inclusion)
        :name: contributing_template_md_code_included_partial
        :emphasize-lines: 2-12
        :pyobject: with_temp_fahrenheit           
        ```

Dropdowns#

You can use a dropdown when you want to have an expandable section in your article. This is especially useful with code-blocks in the conclusion or as an inclusion as reference.

````{dropdown} [template-md in a dropdown](./template-md.md)
```{literalinclude} template-md.md
:language: markdown
```
````

You can also have the dropdown opened by default by adding :open: to the first line.

````{dropdown} [template-md.md](./template-md.md)
:open:
```{literalinclude} template-md.md
:language: markdown
```
````

Tables#

For simple tables, use the Markdown syntax.

Link	Code
Header example	{ref}`target`
Alternative text	{ref}`Alternative text <target>`

is obtained with the following code:

| Link                             | Code                                    |
|----------------------------------|-----------------------------------------|
| {ref}`target`                    | ```{ref}`target` ```                    | 
| {ref}`Alternative text <target>` | ```{ref}`Alternative text <target>` ``` |

You can right-align a column with ---: or center with :---:. If you need a more advanced table, you have to fall back to the rst syntax:

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Table cells contain body elements.
body row 4	Cells may span rows.	Table cells contain body elements.
body row 5	Cells may also be empty: `-->`

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+----------+----------+
| body row 5             | Cells may also be     |          |
|                        | empty: ``-->``        |          |
+------------------------+-----------------------+----------+  

Or with list-table (which works also with code)

Title#
Heading row 1, column 1	Heading row 1, column 2	Heading row 1, column 3
import dataiku client = dataiku.api_client()		Row 1, column 3
Row 2, column 1	Row 2, column 2	Row 2, column 3

.. list-table:: Title
  :name: contributing_template_md_table
  :widths: 4 1 3
  :header-rows: 1
  
  * - Heading row 1, column 1
    - Heading row 1, column 2
    - Heading row 1, column 3
  * - .. code-block:: python
        
        import dataiku
        
        client = dataiku.api_client()
        
    -
    - Row 1, column 3
  * - Row 2, column 1
    - Row 2, column 2
    - Row 2, column 3

Admonitions#

You can use all admonitions defined in Sphinx (topic, admonition, attention, caution, danger, error, hint, important, note, seealso, tip, and warning). These admonitions are renderer like the following:

admonition_title

Lorem ipsum dolor sit amet consectetur adipisicing elit. Accusamus, sunt voluptatum tenetur libero nulla esse veritatis accusantium earum commodi hic voluptatem officia culpa optio atque. Quaerat sed quibusdam ratione nam.

Attention

Caution

Danger

Error

Hint

Important

Note

Mathematics and formula#

Sphinx uses $\LaTeX$ notation to render the formula. You can use the $ sign to delimitate an inline equation. For example, this inline equation $e=mc^2$ is rendered with $e=mc^2$ or {math}`e=mc^2` .

You can also have equations block with the $$ symbol:

\[\begin{split} \begin{aligned} a & = b\\ a^2 & = ab\\ a^2 - b^2 & = ab - b^2\\ (a - b)(a + b) & = b(a - b)\\ \end{aligned} \end{split}\]

  $$
  \begin{aligned}
    a & = b\\
    a^2 & = ab\\
    a^2 - b^2 & = ab - b^2\\
    (a - b)(a + b) & = b(a - b)\\
  \end{aligned}
  $$

And with the {math} for numbering, see (1)

(1)#\[\begin{split}\begin{aligned} x^2 - x^2 & = x^2 - x^2\\ x (x - x) & = (x + x) (x - x)\\ \end{aligned}\end{split}\]

    ```{math}
    :label: contributing_template_md_math_absurd2
    
    \begin{aligned}
      x^2 - x^2 & = x^2 - x^2\\
      x (x - x) & = (x + x) (x - x)\\
    \end{aligned}
    ```