diff --git a/latest/generated/example.html b/latest/generated/example.html index fc3973f..43de642 100644 --- a/latest/generated/example.html +++ b/latest/generated/example.html @@ -1,3 +1,13 @@ 7. Example · Literate.jl
7. Example

7. Example

This is an example generated with Literate based on this source file: example.jl. You are seeing the html-output which Documenter have generated based on a markdown file generated with Literate. The corresponding notebook can be found here: example.ipynb, and the plain script output can be found here: example.jl.

It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

Basic syntax

The basic syntax for Literate is simple, lines starting with #' is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

x = 1//3
-y = 2//5
2//5

In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

It is possible to filter lines by starting it with #md, #nb or #jl for markdown, notebook and script output only, respectively. This line is filtered out for notebook and script output.

The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

x + y
11//15
x * y
2//15

Custom processing

It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

z = 1.0 + 2.0im
1.0 + 2.0im

Documenter.jl interaction

In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

\[\int f(x) dx\]

using Documenters math syntax. This is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly in the notebook too.

This page was generated using Literate.jl.

+y = 2//5
2//5

In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

It is possible to filter lines by starting it with #md, #nb or #jl for markdown, notebook and script output only, respectively. This line is filtered out for notebook and script output.

The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

x + y
11//15
x * y
2//15

Output Capturing

Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

function foo()
+    println("This string is printed to stdout.")
+    return [1, 2, 3, 4]
+end
+
+foo()
This string is printed to stdout.
+4-element Array{Int64,1}:
+ 1
+ 2
+ 3
+ 4

Custom processing

It is possible to give Literate custom pre- and post-processing functions. For example, here we insert two placeholders, which we will replace with something else at time of generation. We have here replaced our placeholders with z and 1.0 + 2.0im:

z = 1.0 + 2.0im
1.0 + 2.0im

Documenter.jl interaction

In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

This page was generated using Literate.jl.

diff --git a/latest/generated/example.ipynb b/latest/generated/example.ipynb index 31884b9..158bf0a 100644 --- a/latest/generated/example.ipynb +++ b/latest/generated/example.ipynb @@ -123,6 +123,49 @@ "metadata": {}, "execution_count": 3 }, + { + "outputs": [], + "cell_type": "markdown", + "source": [ + "### Output Capturing\n", + "Code chunks are by default placed in Documenter `@example` blocks in the generated\n", + "markdown. This means that the output will be captured in a block when Documenter is\n", + "building the docs. In notebooks the output is captured in output cells, if the\n", + "`execute` keyword argument is set to true. Output to `stdout`/`stderr` is also\n", + "captured." + ], + "metadata": {} + }, + { + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "This string is printed to stdout.\n" + ] + }, + { + "output_type": "execute_result", + "data": { + "text/plain": "4-element Array{Int64,1}:\n 1\n 2\n 3\n 4" + }, + "metadata": {}, + "execution_count": 4 + } + ], + "cell_type": "code", + "source": [ + "function foo()\n", + " println(\"This string is printed to stdout.\")\n", + " return [1, 2, 3, 4]\n", + "end\n", + "\n", + "foo()" + ], + "metadata": {}, + "execution_count": 4 + }, { "outputs": [], "cell_type": "markdown", @@ -144,7 +187,7 @@ "text/plain": "1.0 + 2.0im" }, "metadata": {}, - "execution_count": 4 + "execution_count": 5 } ], "cell_type": "code", @@ -152,7 +195,7 @@ "z = 1.0 + 2.0im" ], "metadata": {}, - "execution_count": 4 + "execution_count": 5 }, { "outputs": [], @@ -165,12 +208,13 @@ "For example, here is a link, but it is only\n", "visible as a link if you are reading the markdown output. We can also\n", "use equations:\n", + "\n", "\\begin{equation}\n", - "\\int f(x) dx\n", + "\\int_\\Omega \\nabla v \\cdot \\nabla u\\ \\mathrm{d}\\Omega = \\int_\\Omega v f\\ \\mathrm{d}\\Omega\n", "\\end{equation}\n", - "using Documenters math syntax. This is automatically changed to\n", - "`\\begin{equation} ... \\end{equation}` in the notebook output to display\n", - "correctly in the notebook too." + "\n", + "using Documenters math syntax. Documenters syntax is automatically changed to\n", + "`\\begin{equation} ... \\end{equation}` in the notebook output to display correctly." ], "metadata": {} }, diff --git a/latest/generated/example.jl b/latest/generated/example.jl index 750a0bd..6e9cc9c 100644 --- a/latest/generated/example.jl +++ b/latest/generated/example.jl @@ -5,6 +5,13 @@ x + y x * y +function foo() + println("This string is printed to stdout.") + return [1, 2, 3, 4] +end + +foo() + z = 1.0 + 2.0im # This file was generated using Literate.jl, https://github.com/fredrikekre/Literate.jl diff --git a/latest/outputformats.html b/latest/outputformats.html index ca4e381..50146b5 100644 --- a/latest/outputformats.html +++ b/latest/outputformats.html @@ -27,7 +27,7 @@ When adding `x` and `y` together we obtain a new rational number: ```@example name z = x + y -```

We note that lines starting with #' is printed as regular markdown, and the code lines have been wrapped in @example blocks.

Some of the output rendering can be controlled with keyword arguments to Literate.markdown:

Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)

Generate a markdown file from inputfile and write the result to the directoryoutputdir.

Keyword arguments:

source

4.2. Notebook Output

The (default) notebook output of the source snippet above is as follows

        │ # Rational numbers
+```

We note that lines starting with #' is printed as regular markdown, and the code lines have been wrapped in @example blocks.

Some of the output rendering can be controlled with keyword arguments to Literate.markdown:

Literate.markdown — Function.
Literate.markdown(inputfile, outputdir; kwargs...)

Generate a markdown file from inputfile and write the result to the directoryoutputdir.

Keyword arguments:

source

4.2. Notebook Output

The (default) notebook output of the source snippet above is as follows

        │ # Rational numbers
         │
         │ In julia rational numbers can be constructed with the `//` operator.
         │ Lets define two rational numbers, `x` and `y`:
@@ -41,8 +41,8 @@ Out[2]: │ 2//5
         │ When adding `x` and `y` together we obtain a new rational number:
 
 In[3]:  │ z = x + y
-Out[3]: │ 11/15

We note that lines starting with #' is put in markdown cells, and the code lines have been put in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:

Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)

Generate a notebook from inputfile and write the result to outputdir.

Keyword arguments:

source

4.3. Script Output

The (default) script output of the source snippet above is as follows

x = 1//3
+Out[3]: │ 11/15

We note that lines starting with #' is put in markdown cells, and the code lines have been put in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed. Some of the output rendering can be controlled with keyword arguments to Literate.notebook:

Literate.notebook — Function.
Literate.notebook(inputfile, outputdir; kwargs...)

Generate a notebook from inputfile and write the result to outputdir.

Keyword arguments:

source

4.3. Script Output

The (default) script output of the source snippet above is as follows

x = 1//3
 
 y = 2//5
 
-z = x + y

We note that lines starting with #' are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

Keyword arguments:

source
+z = x + y

We note that lines starting with #' are removed and only the code lines have been kept. Some of the output rendering can be controlled with keyword arguments to Literate.script:

Literate.script — Function.
Literate.script(inputfile, outputdir; kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

Keyword arguments:

source
diff --git a/latest/search_index.js b/latest/search_index.js index 419ee30..6bfae8b 100644 --- a/latest/search_index.js +++ b/latest/search_index.js @@ -280,6 +280,14 @@ var documenterSearchIndex = {"docs": [ "text": "The basic syntax for Literate is simple, lines starting with #\' is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:x = 1//3\ny = 2//5In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.It is possible to filter lines by starting it with #md, #nb or #jl for markdown, notebook and script output only, respectively. This line is filtered out for notebook and script output.The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.x + yx * y" }, +{ + "location": "generated/example.html#Output-Capturing-1", + "page": "7. Example", + "title": "Output Capturing", + "category": "section", + "text": "Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.function foo()\n println(\"This string is printed to stdout.\")\n return [1, 2, 3, 4]\nend\n\nfoo()" +}, + { "location": "generated/example.html#Custom-processing-1", "page": "7. Example", @@ -293,7 +301,7 @@ var documenterSearchIndex = {"docs": [ "page": "7. Example", "title": "Documenter.jl interaction", "category": "section", - "text": "In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:int f(x) dxusing Documenters math syntax. This is automatically changed to \\begin{equation} ... \\end{equation} in the notebook output to display correctly in the notebook too.This page was generated using Literate.jl." + "text": "In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:int_Omega nabla v cdot nabla u mathrmdOmega = int_Omega v f mathrmdOmegausing Documenters math syntax. Documenters syntax is automatically changed to \\begin{equation} ... \\end{equation} in the notebook output to display correctly.This page was generated using Literate.jl." }, ]}