From daddc40dbe206e5e67ff4e85aec6ee48693ec94d Mon Sep 17 00:00:00 2001 From: autodocs Date: Wed, 25 Apr 2018 07:20:27 +0000 Subject: [PATCH] build based on ec6a9d3 --- latest/fileformat.html | 5 +++-- latest/generated/example.html | 2 +- latest/generated/example.ipynb | 6 +++--- latest/outputformats.html | 6 +++--- latest/search_index.js | 6 +++--- 5 files changed, 13 insertions(+), 12 deletions(-) diff --git a/latest/fileformat.html b/latest/fileformat.html index d2bc139..2ea4848 100644 --- a/latest/fileformat.html +++ b/latest/fileformat.html @@ -9,8 +9,9 @@ y = 2//5 #' When adding `x` and `y` together we obtain a new rational number: -z = x + y

In the lines #' we can use regular markdown syntax, for example the # used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:

For simple use this is all you need to know. The following additional special syntax can also be used:

There is also some default convenience replacements that will always be performed, see Default Replacements.

2.2. Filtering Lines

It is possible to filter out lines depending on the output format. For this purpose, there are three different "tokens" that can be placed on the start of the line:

Lines starting with one of these tokens are filtered out in the preprocessing step.

Suppose, for example, that we want to include a docstring within a @docs block using Documenter. Obviously we don't want to include this in the notebook, since @docs is Documenter syntax that the notebook will not understand. This is a case where we can prepend #md to those lines:

#md #' ```@docs
+z = x + y

In the lines #' we can use regular markdown syntax, for example the # used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:

For simple use this is all you need to know. The following additional special syntax can also be used:

There is also some default convenience replacements that will always be performed, see Default Replacements.

2.2. Filtering Lines

It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:

Lines starting with one of these tokens are filtered out in the preprocessing step.

Suppose, for example, that we want to include a docstring within a @docs block using Documenter. Obviously we don't want to include this in the notebook, since @docs is Documenter syntax that the notebook will not understand. This is a case where we can prepend #md to those lines:

#md #' ```@docs
 #md #' Literate.markdown
 #md #' Literate.notebook
 #md #' Literate.markdown
-#md #' ```

The lines in the example above would be filtered out in the preprocessing step, unless we are generating a markdown file. When generating a markdown file we would simple remove the leading #md from the lines. Beware that the space after the tag is also removed.

2.3. Default Replacements

The following convenience "macros" are always expanded:

+#md #' ```

The lines in the example above would be filtered out in the preprocessing step, unless we are generating a markdown file. When generating a markdown file we would simple remove the leading #md from the lines. Beware that the space after the tag is also removed.

The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:

using Test                      #src
+@test result == expected_result #src

2.3. Default Replacements

The following convenience "macros" are always expanded:

diff --git a/latest/generated/example.html b/latest/generated/example.html index 43de642..7103e2d 100644 --- a/latest/generated/example.html +++ b/latest/generated/example.html @@ -1,6 +1,6 @@ 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

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()
+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 out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):

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
diff --git a/latest/generated/example.ipynb b/latest/generated/example.ipynb
index 158bf0a..ca0f994 100644
--- a/latest/generated/example.ipynb
+++ b/latest/generated/example.ipynb
@@ -68,9 +68,9 @@
    "outputs": [],
    "cell_type": "markdown",
    "source": [
-    "It is possible to filter lines by starting it with `#md`, `#nb` or `#jl`\n",
-    "for markdown, notebook and script output only, respectively.\n",
-    "This line is filtered out for markdown and script output."
+    "It is possible to filter out lines depending on the output using the\n",
+    "`#md`, `#nb`, `#jl` and `#src` tags (see Filtering Lines):\n",
+    "- This line starts with `#nb` and is thus only visible in the notebook output."
    ],
    "metadata": {}
   },
diff --git a/latest/outputformats.html b/latest/outputformats.html
index 50146b5..3e3b7c1 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 6bfae8b..5a4b6a5 100644 --- a/latest/search_index.js +++ b/latest/search_index.js @@ -53,7 +53,7 @@ var documenterSearchIndex = {"docs": [ "page": "2. File Format", "title": "2.1. Syntax", "category": "section", - "text": "The basic syntax is simple:lines starting with #\' is treated as markdown,\nall other lines are treated as julia code.The reason for using #\' instead of # is that we want to be able to use # as comments, just as in a regular script. Lets look at a simple example:#\' # Rational numbers\n#\'\n#\' In julia rational numbers can be constructed with the `//` operator.\n#\' Lets define two rational numbers, `x` and `y`:\n\nx = 1//3\ny = 2//5\n\n#\' When adding `x` and `y` together we obtain a new rational number:\n\nz = x + yIn the lines #\' we can use regular markdown syntax, for example the # used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:The script is valid julia, which means that we can include it and the example will run (for example in the test/runtests.jl script, to include the example in the test suite).\nThe script is \"self-explanatory\", i.e. the markdown lines works as comments and thus serve as good documentation on its own.For simple use this is all you need to know. The following additional special syntax can also be used:#md, #nb, #jl: tags for filtering of lines, see Filtering Lines.\n#-: tag for manually controlling chunk-splits, see Custom control over chunk splits.There is also some default convenience replacements that will always be performed, see Default Replacements." + "text": "The basic syntax is simple:lines starting with #\' is treated as markdown,\nall other lines are treated as julia code.The reason for using #\' instead of # is that we want to be able to use # as comments, just as in a regular script. Lets look at a simple example:#\' # Rational numbers\n#\'\n#\' In julia rational numbers can be constructed with the `//` operator.\n#\' Lets define two rational numbers, `x` and `y`:\n\nx = 1//3\ny = 2//5\n\n#\' When adding `x` and `y` together we obtain a new rational number:\n\nz = x + yIn the lines #\' we can use regular markdown syntax, for example the # used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:The script is valid julia, which means that we can include it and the example will run (for example in the test/runtests.jl script, to include the example in the test suite).\nThe script is \"self-explanatory\", i.e. the markdown lines works as comments and thus serve as good documentation on its own.For simple use this is all you need to know. The following additional special syntax can also be used:#md, #nb, #jl, #src: tags to filter lines, see Filtering Lines,\n#-: tag to manually control chunk-splits, see Custom control over chunk splits.There is also some default convenience replacements that will always be performed, see Default Replacements." }, { @@ -61,7 +61,7 @@ var documenterSearchIndex = {"docs": [ "page": "2. File Format", "title": "2.2. Filtering Lines", "category": "section", - "text": "It is possible to filter out lines depending on the output format. For this purpose, there are three different \"tokens\" that can be placed on the start of the line:#md: markdown output only,\n#nb: notebook output only,\n#jl: script output only.Lines starting with one of these tokens are filtered out in the preprocessing step.Suppose, for example, that we want to include a docstring within a @docs block using Documenter. Obviously we don\'t want to include this in the notebook, since @docs is Documenter syntax that the notebook will not understand. This is a case where we can prepend #md to those lines:#md #\' ```@docs\n#md #\' Literate.markdown\n#md #\' Literate.notebook\n#md #\' Literate.markdown\n#md #\' ```The lines in the example above would be filtered out in the preprocessing step, unless we are generating a markdown file. When generating a markdown file we would simple remove the leading #md from the lines. Beware that the space after the tag is also removed." + "text": "It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of \"tokens\" that can be used to mark the purpose of certain lines:#md: line exclusive to markdown output,\n#nb: line exclusive to notebook output,\n#jl: line exclusive to script output,\n#src: line exclusive to the source code and thus filtered out unconditionally.Lines starting with one of these tokens are filtered out in the preprocessing step.Suppose, for example, that we want to include a docstring within a @docs block using Documenter. Obviously we don\'t want to include this in the notebook, since @docs is Documenter syntax that the notebook will not understand. This is a case where we can prepend #md to those lines:#md #\' ```@docs\n#md #\' Literate.markdown\n#md #\' Literate.notebook\n#md #\' Literate.markdown\n#md #\' ```The lines in the example above would be filtered out in the preprocessing step, unless we are generating a markdown file. When generating a markdown file we would simple remove the leading #md from the lines. Beware that the space after the tag is also removed.The #src token can also be placed at the end of a line. This is to make it possible to have code lines exclusive to the source code, and not just comment lines. For example, if the source file is included in the test suite we might want to add a @test at the end without this showing up in the outputs:using Test #src\n@test result == expected_result #src" }, { @@ -277,7 +277,7 @@ var documenterSearchIndex = {"docs": [ "page": "7. Example", "title": "Basic syntax", "category": "section", - "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" + "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 out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering Lines):This line starts with #md and is thus only visible in the markdown 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" }, {