From 7aaa230d96c3adf6cefa0a1b1839c0fc9527ff55 Mon Sep 17 00:00:00 2001 From: autodocs Date: Sat, 21 Apr 2018 20:03:13 +0000 Subject: [PATCH] build based on 7cea759 --- latest/generated/example.html | 2 +- latest/generated/example.ipynb | 8 ++++++++ latest/generated/example.jl | 2 ++ latest/outputformats.html | 6 +++--- latest/search_index.js | 2 +- 5 files changed, 15 insertions(+), 5 deletions(-) diff --git a/latest/generated/example.html b/latest/generated/example.html index 70b1bc4..fc3973f 100644 --- a/latest/generated/example.html +++ b/latest/generated/example.html @@ -1,3 +1,3 @@ 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.

+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.

diff --git a/latest/generated/example.ipynb b/latest/generated/example.ipynb index 4f919a8..31884b9 100644 --- a/latest/generated/example.ipynb +++ b/latest/generated/example.ipynb @@ -173,6 +173,14 @@ "correctly in the notebook too." ], "metadata": {} + }, + { + "outputs": [], + "cell_type": "markdown", + "source": [ + "*This notebook was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*" + ], + "metadata": {} } ], "nbformat_minor": 3, diff --git a/latest/generated/example.jl b/latest/generated/example.jl index 025e604..750a0bd 100644 --- a/latest/generated/example.jl +++ b/latest/generated/example.jl @@ -7,3 +7,5 @@ x * y 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 9671b21..ca4e381 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:

  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.

  • codefence: A Pair of opening and closing code fence. Defaults to

    "```@example $(name)" => "```"

    if documenter = true and

    "```julia" => "```"

    if documenter = false.

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:

  • name: name of the output file, excluding .md. name is also used to name all the @example blocks, and to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that tells if the output is intended to use with Documenter.jl. Defaults to true. See the the manual section on Interaction with Documenter.

  • codefence: A Pair of opening and closing code fence. Defaults to

    "```@example $(name)" => "```"

    if documenter = true and

    "```julia" => "```"

    if documenter = false.

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:

  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.

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:

  • name: name of the output file, excluding .ipynb. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • execute: a boolean deciding if the generated notebook should also be executed or not. Defaults to true. The current working directory is set to outputdir when executing the notebook.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during notebook generation. Defaults to true. See the the manual section on Interaction with Documenter.

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:

  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.

  • keep_comments: boolean that, if set to true, keeps markdown lines (#') as comments in the output script. Defaults to false.

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:

  • name: name of the output file, excluding .jl. name is also used to replace @__NAME__. Defaults to the filename of inputfile.

  • preprocess, postprocess: custom pre- and post-processing functions, see the Custom pre- and post-processing section of the manual. Defaults to identity.

  • documenter: boolean that says if the source contains Documenter.jl specific things to filter out during script generation. Defaults to true. See the the manual section on Interaction with Documenter.

  • keep_comments: boolean that, if set to true, keeps markdown lines (#') as comments in the output script. Defaults to false.

source
diff --git a/latest/search_index.js b/latest/search_index.js index a1aebf3..419ee30 100644 --- a/latest/search_index.js +++ b/latest/search_index.js @@ -293,7 +293,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." + "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." }, ]}