r
/
Literate.jl
mirror of https://github.com/fredrikekre/Literate.jl
1
0
Fork 0
Code Releases Activity
Browse Source

Various documentation updates. (#157)

pull/158/head
Fredrik Ekre 4 years ago committed by GitHub
parent
79615c90f1
commit
6d3b76a006
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 108 additions and 126 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 60
      docs/Manifest.toml
  2. 2
      docs/src/customprocessing.md
  3. 77
      docs/src/fileformat.md
  4. 52
      docs/src/outputformats.md
  5. 2
      docs/src/pipeline.md
  6. 2
      docs/src/tips.md
  7. 4
      examples/example.jl
  8. 24
      src/Literate.jl
  9. 11
      test/runtests.jl

60
docs/Manifest.toml
Unescape View File

@ -29,9 +29,9 @@ version = "1.16.0+6"
[[ColorSchemes]] [[ColorSchemes]]
deps = ["ColorTypes", "Colors", "FixedPointNumbers", "Random", "StaticArrays"] deps = ["ColorTypes", "Colors", "FixedPointNumbers", "Random", "StaticArrays"]
git-tree-sha1 = "c8fd01e4b736013bc61b704871d20503b33ea402" git-tree-sha1 = "ed268efe58512df8c7e224d2e170afd76dd6a417"
uuid = "35d6a980-a343-548e-a6ea-1d62b119f2f4" uuid = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
version = "3.12.1" version = "3.13.0"
[[ColorTypes]] [[ColorTypes]]
deps = ["FixedPointNumbers", "Random"] deps = ["FixedPointNumbers", "Random"]
@ -47,9 +47,9 @@ version = "0.12.8"
[[Compat]] [[Compat]]
deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "SHA", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"] deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "SHA", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"]
git-tree-sha1 = "e4e2b39db08f967cc1360951f01e8a75ec441cab" git-tree-sha1 = "dc7dedc2c2aa9faf59a55c622760a25cbefbe941"
uuid = "34da2185-b29b-5c13-b0c7-acf172513d20" uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
version = "3.30.0" version = "3.31.0"
[[CompilerSupportLibraries_jll]] [[CompilerSupportLibraries_jll]]
deps = ["Artifacts", "Libdl"] deps = ["Artifacts", "Libdl"]
@ -62,9 +62,9 @@ uuid = "d38c429a-6771-53c6-b99e-75d170b6e991"
version = "0.5.7" version = "0.5.7"
[[DataAPI]] [[DataAPI]]
git-tree-sha1 = "dfb3b7e89e395be1e25c2ad6d7690dc29cc53b1d" git-tree-sha1 = "ee400abb2298bd13bfc3df1c412ed228061a2385"
uuid = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a" uuid = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a"
version = "1.6.0" version = "1.7.0"
[[DataStructures]] [[DataStructures]]
deps = ["Compat", "InteractiveUtils", "OrderedCollections"] deps = ["Compat", "InteractiveUtils", "OrderedCollections"]
@ -97,9 +97,9 @@ version = "0.8.5"
[[Documenter]] [[Documenter]]
deps = ["Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"] deps = ["Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
git-tree-sha1 = "621850838b3e74dd6dd047b5432d2e976877104e" git-tree-sha1 = "47f13b6305ab195edb73c86815962d84e31b0f48"
uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4" uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
version = "0.27.2" version = "0.27.3"
[[Downloads]] [[Downloads]]
deps = ["ArgTools", "LibCURL", "NetworkOptions"] deps = ["ArgTools", "LibCURL", "NetworkOptions"]
@ -179,9 +179,9 @@ version = "0.57.3+0"
[[GeometryBasics]] [[GeometryBasics]]
deps = ["EarCut_jll", "IterTools", "LinearAlgebra", "StaticArrays", "StructArrays", "Tables"] deps = ["EarCut_jll", "IterTools", "LinearAlgebra", "StaticArrays", "StructArrays", "Tables"]
git-tree-sha1 = "4136b8a5668341e58398bb472754bff4ba0456ff" git-tree-sha1 = "15ff9a14b9e1218958d3530cc288cf31465d9ae2"
uuid = "5c1252a2-5f33-56bf-86c9-59e7332b4326" uuid = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
version = "0.3.12" version = "0.3.13"
[[Gettext_jll]] [[Gettext_jll]]
deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "Libdl", "Libiconv_jll", "Pkg", "XML2_jll"] deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "Libdl", "Libiconv_jll", "Pkg", "XML2_jll"]
@ -201,10 +201,10 @@ uuid = "42e2da0e-8278-4e71-bc24-59509adca0fe"
version = "1.0.2" version = "1.0.2"
[[HTTP]] [[HTTP]]
deps = ["Base64", "Dates", "IniFile", "MbedTLS", "NetworkOptions", "Sockets", "URIs"] deps = ["Base64", "Dates", "IniFile", "Logging", "MbedTLS", "NetworkOptions", "Sockets", "URIs"]
git-tree-sha1 = "86ed84701fbfd1142c9786f8e53c595ff5a4def9" git-tree-sha1 = "c6a1fff2fd4b1da29d3dccaffb1e1001244d844e"
uuid = "cd3eb016-35fb-5094-929b-558a96fad6f3" uuid = "cd3eb016-35fb-5094-929b-558a96fad6f3"
version = "0.9.10" version = "0.9.12"
[[IOCapture]] [[IOCapture]]
deps = ["Logging", "Random"] deps = ["Logging", "Random"]
@ -457,15 +457,15 @@ version = "2.0.1"
[[PlotUtils]] [[PlotUtils]]
deps = ["ColorSchemes", "Colors", "Dates", "Printf", "Random", "Reexport", "Statistics"] deps = ["ColorSchemes", "Colors", "Dates", "Printf", "Random", "Reexport", "Statistics"]
git-tree-sha1 = "ae9a295ac761f64d8c2ec7f9f24d21eb4ffba34d" git-tree-sha1 = "501c20a63a34ac1d015d5304da0e645f42d91c9f"
uuid = "995b91a9-d308-5afd-9ec6-746e21dbc043" uuid = "995b91a9-d308-5afd-9ec6-746e21dbc043"
version = "1.0.10" version = "1.0.11"
[[Plots]] [[Plots]]
deps = ["Base64", "Contour", "Dates", "FFMPEG", "FixedPointNumbers", "GR", "GeometryBasics", "JSON", "Latexify", "LinearAlgebra", "Measures", "NaNMath", "PlotThemes", "PlotUtils", "Printf", "REPL", "Random", "RecipesBase", "RecipesPipeline", "Reexport", "Requires", "Scratch", "Showoff", "SparseArrays", "Statistics", "StatsBase", "UUIDs"] deps = ["Base64", "Contour", "Dates", "FFMPEG", "FixedPointNumbers", "GR", "GeometryBasics", "JSON", "Latexify", "LinearAlgebra", "Measures", "NaNMath", "PlotThemes", "PlotUtils", "Printf", "REPL", "Random", "RecipesBase", "RecipesPipeline", "Reexport", "Requires", "Scratch", "Showoff", "SparseArrays", "Statistics", "StatsBase", "UUIDs"]
git-tree-sha1 = "e995fa1821b6daff8b107a8eafbec234ae2263d0" git-tree-sha1 = "b93181645c1209d912d5632ba2d0094bc00703ad"
uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
version = "1.16.5" version = "1.18.1"
[[Preferences]] [[Preferences]]
deps = ["TOML"] deps = ["TOML"]
@ -498,9 +498,9 @@ version = "1.1.1"
[[RecipesPipeline]] [[RecipesPipeline]]
deps = ["Dates", "NaNMath", "PlotUtils", "RecipesBase"] deps = ["Dates", "NaNMath", "PlotUtils", "RecipesBase"]
git-tree-sha1 = "7a5026a6741c14147d1cb6daf2528a77ca28eb51" git-tree-sha1 = "2a7a2469ed5d94a98dea0e85c46fa653d76be0cd"
uuid = "01d81517-befc-4cb6-b9ec-a95719d0359c" uuid = "01d81517-befc-4cb6-b9ec-a95719d0359c"
version = "0.3.2" version = "0.3.4"
[[Reexport]] [[Reexport]]
git-tree-sha1 = "5f6c21241f0f655da3952fd60aa18477cf96c220" git-tree-sha1 = "5f6c21241f0f655da3952fd60aa18477cf96c220"
@ -540,9 +540,9 @@ uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
[[SortingAlgorithms]] [[SortingAlgorithms]]
deps = ["DataStructures"] deps = ["DataStructures"]
git-tree-sha1 = "2ec1962eba973f383239da22e75218565c390a96" git-tree-sha1 = "b3363d7460f7d098ca0912c69b082f75625d7508"
uuid = "a2af1166-a08f-5f64-846c-94a0d3cef48c" uuid = "a2af1166-a08f-5f64-846c-94a0d3cef48c"
version = "1.0.0" version = "1.0.1"
[[SparseArrays]] [[SparseArrays]]
deps = ["LinearAlgebra", "Random"] deps = ["LinearAlgebra", "Random"]
@ -550,9 +550,9 @@ uuid = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
[[StaticArrays]] [[StaticArrays]]
deps = ["LinearAlgebra", "Random", "Statistics"] deps = ["LinearAlgebra", "Random", "Statistics"]
git-tree-sha1 = "42378d3bab8b4f57aa1ca443821b752850592668" git-tree-sha1 = "a43a7b58a6e7dc933b2fa2e0ca653ccf8bb8fd0e"
uuid = "90137ffa-7385-5640-81b9-e52037218182" uuid = "90137ffa-7385-5640-81b9-e52037218182"
version = "1.2.2" version = "1.2.6"
[[Statistics]] [[Statistics]]
deps = ["LinearAlgebra", "SparseArrays"] deps = ["LinearAlgebra", "SparseArrays"]
@ -570,10 +570,10 @@ uuid = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
version = "0.33.8" version = "0.33.8"
[[StructArrays]] [[StructArrays]]
deps = ["Adapt", "DataAPI", "Tables"] deps = ["Adapt", "DataAPI", "StaticArrays", "Tables"]
git-tree-sha1 = "44b3afd37b17422a62aea25f04c1f7e09ce6b07f" git-tree-sha1 = "000e168f5cc9aded17b6999a560b7c11dda69095"
uuid = "09ab397b-f2b6-538f-b94a-2f83cf4a842a" uuid = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
version = "0.5.1" version = "0.6.0"
[[TOML]] [[TOML]]
deps = ["Dates"] deps = ["Dates"]
@ -587,9 +587,9 @@ version = "1.0.1"
[[Tables]] [[Tables]]
deps = ["DataAPI", "DataValueInterfaces", "IteratorInterfaceExtensions", "LinearAlgebra", "TableTraits", "Test"] deps = ["DataAPI", "DataValueInterfaces", "IteratorInterfaceExtensions", "LinearAlgebra", "TableTraits", "Test"]
git-tree-sha1 = "aa30f8bb63f9ff3f8303a06c604c8500a69aa791" git-tree-sha1 = "8ed4a3ea724dac32670b062be3ef1c1de6773ae8"
uuid = "bd369af6-aec1-5ad0-b16a-f7cc5008161c" uuid = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
version = "1.4.3" version = "1.4.4"
[[Tar]] [[Tar]]
deps = ["ArgTools", "SHA"] deps = ["ArgTools", "SHA"]
@ -613,9 +613,9 @@ uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
[[Wayland_jll]] [[Wayland_jll]]
deps = ["Artifacts", "Expat_jll", "JLLWrappers", "Libdl", "Libffi_jll", "Pkg", "XML2_jll"] deps = ["Artifacts", "Expat_jll", "JLLWrappers", "Libdl", "Libffi_jll", "Pkg", "XML2_jll"]
git-tree-sha1 = "dc643a9b774da1c2781413fd7b6dcd2c56bb8056" git-tree-sha1 = "3e61f0b86f90dacb0bc0e73a0c5a83f6a8636e23"
uuid = "a2964d1f-97da-50d4-b82a-358c7fce9d89" uuid = "a2964d1f-97da-50d4-b82a-358c7fce9d89"
version = "1.17.0+4" version = "1.19.0+0"
[[Wayland_protocols_jll]] [[Wayland_protocols_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg", "Wayland_jll"] deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg", "Wayland_jll"]

2
docs/src/customprocessing.md
Unescape View File

@ -4,7 +4,7 @@ Since all packages are different, and may have different demands on how
to create a nice example for the documentation it is important that to create a nice example for the documentation it is important that
the package maintainer does not feel limited by the by default provided syntax the package maintainer does not feel limited by the by default provided syntax
that this package offers. While you can generally come a long way by utilizing that this package offers. While you can generally come a long way by utilizing
[line filtering](@ref Filtering-Lines) there might be situations where you need [line filtering](@ref Filtering-lines) there might be situations where you need
to manually hook into the generation and change things. In Literate this to manually hook into the generation and change things. In Literate this
is done by letting the user supply custom pre- and post-processing functions is done by letting the user supply custom pre- and post-processing functions
that may do transformation of the content. that may do transformation of the content.

77
docs/src/fileformat.md
Unescape View File

@ -1,4 +1,4 @@
# [**2.** File Format](@id File-Format) # [**2.** File format](@id File-format)
The source file format for Literate is a regular, commented, julia (`.jl`) scripts. The source file format for Literate is a regular, commented, julia (`.jl`) scripts.
The idea is that the scripts also serve as documentation on their own and it is also The idea is that the scripts also serve as documentation on their own and it is also
@ -39,39 +39,40 @@ julia code. We note a couple of things:
thus serve as good documentation on its own. 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: 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](@ref Filtering-Lines), - `#md`, `#nb`, `#jl`, `#src`: tags to filter lines, see [Filtering lines](@ref Filtering-lines),
- `#-` (`#+`): tag to manually control chunk-splits, see [Custom control over chunk splits](@ref). - `#-` (`#+`): tag to manually control chunk-splits, see [Custom control over chunk splits](@ref).
There is also some default convenience replacements that will always be performed, see There is also some default convenience replacements that will always be performed, see
[Default Replacements](@ref). [Default replacements](@ref).
!!! compat "Multiline comments in Literate 2.7" ### Multiline comments
Literate version 2.7 adds support for Julia multiline comments for markdown input.
All multiline comments in the input are rewritten to regular comments as part of the Literate version 2.7 adds support for Julia multiline comments for markdown input.
preprocessing step, before any other processing is performed. For Literate to recognize All multiline comments in the input are rewritten to regular comments as part of the
multiline comments it is required that the start token (`#=`) and end token (`=#`) are preprocessing step, before any other processing is performed. For Literate to recognize
placed on their own lines. Note also that it is allowed to have more than one `=` in the multiline comments it is required that the start token (`#=`) and end token (`=#`) are
tokens, for example placed *on their own lines*. Note also that it is allowed to have more than one `=` in the
```juila tokens, for example
#= ```juila
This multiline comment #=
is treated as markdown. This multiline comment
=# is treated as markdown.
=#
#=====================
This is also markdown. #=====================
=====================# This is also markdown.
``` =====================#
is rewritten to ```
```juila is rewritten to
# This multiline comment ```juila
# is treated as markdown. # This multiline comment
# is treated as markdown.
# This is also markdown.
``` # This is also markdown.
```
## [**2.2.** Filtering Lines](@id Filtering-Lines)
## [**2.2.** Filtering lines](@id Filtering-lines)
It is often useful to filter out lines in the source depending on the output format. 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 For this purpose there are a number of "tokens" that can be used to mark the purpose of
@ -91,12 +92,6 @@ ending with `#hide` are filtered out similar to Documenter.jl.
are filtered out *before* execution (if `execute=true`) and `#hide` lines are filtered out *before* execution (if `execute=true`) and `#hide` lines
are filtered out *after* execution. are filtered out *after* execution.
!!! compat "Literate 2.6"
The `#hide` token requires at least Literate version 2.6.
!!! compat "Literate 2.3"
Filter tokens at the *end of the line* requires at least Literate version 2.3.
!!! tip !!! tip
The tokens can also be negated, for example a line starting with `#!nb` would The tokens can also be negated, for example a line starting with `#!nb` would
be included in markdown and script output, but filtered out for notebook output. be included in markdown and script output, but filtered out for notebook output.
@ -127,7 +122,7 @@ using Test #src
``` ```
## [**2.3.** Default Replacements](@id Default-Replacements) ## [**2.3.** Default replacements](@id Default-replacements)
The following convenience "macros"/source placeholders are always expanded: The following convenience "macros"/source placeholders are always expanded:
@ -162,9 +157,3 @@ The following convenience "macros"/source placeholders are always expanded:
``` ```
This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI,
but can be configured, see [Configuration](@ref Configuration). but can be configured, see [Configuration](@ref Configuration).
!!! compat "Literate 2.1"
GitHub Actions support for the macros above requires at least Literate version 2.1.
!!! compat "Literate 2.2"
GitLab CI support for the macros above requires at least Literate version 2.2.

52
docs/src/outputformats.md
Unescape View File

@ -1,4 +1,4 @@
# [**4.** Output Formats](@id Output-Formats) # [**4.** Output formats](@id Output-formats)
When the source is parsed, and has been processed it is time to render the output. When the source is parsed, and has been processed it is time to render the output.
We will consider the following source snippet: We will consider the following source snippet:
@ -10,10 +10,14 @@ Markdown.parse("```julia\n" * rstrip(read("outputformats.jl", String)) * "\n```"
and see how this is rendered in each of the output formats. and see how this is rendered in each of the output formats.
## [**4.1.** Markdown Output](@id Markdown-Output) ## [**4.1.** Markdown output](@id Markdown-output)
Markdown output is generated by [`Literate.markdown`](@ref). The (default) markdown output Markdown output is generated by [`Literate.markdown`](@ref). There exist various "flavors"
of the source snippet above is as follows: of markdown and Literate supports some different flavors, see [Markdown flavors](@ref).
The default flavor is `Literate.DocumenterFlavor()` and, as the name suggest, it generates
markdown files meant to be used together with [Documenter.jl]
(https://juliadocs.github.io/Documenter.jl). The output of the source snippet above is as
follows:
```@eval ```@eval
import Markdown import Markdown
@ -29,7 +33,8 @@ an `@meta` block have been added, that sets the `EditURL` variable. This is used
by Documenter to redirect the "Edit on GitHub" link for the page, by Documenter to redirect the "Edit on GitHub" link for the page,
see [Interaction with Documenter](@ref). see [Interaction with Documenter](@ref).
The `@example` blocks are wrapped in 4 consecutive backticks so as to allow for docstrings containing triple backticks, for example: The `@example` blocks are wrapped in 4 consecutive backticks so as to allow for docstrings
containing triple backticks, for example:
````julia ````julia
""" """
This function perform the following calculation: This function perform the following calculation:
@ -39,7 +44,8 @@ This function perform the following calculation:
""" """
f(x) = x[1] + x[2] f(x) = x[1] + x[2]
```` ````
If your Julia code itself contains 4 consecutive backticks, you can use the keyword argument `codefence` to setup 5 backticks for code blocks, see [Configuration](@ref). If your Julia code itself contains 4 consecutive backticks, you can use the keyword
argument `codefence` to setup 5 backticks for code blocks, see [Configuration](@ref).
It possible to configure `Literate.markdown` to also evaluate code snippets, capture the It possible to configure `Literate.markdown` to also evaluate code snippets, capture the
result and include it in the output, by passing `execute=true` as a keyword argument. result and include it in the output, by passing `execute=true` as a keyword argument.
@ -54,17 +60,14 @@ x = 1//3
````` `````
In this example the output is just plain text. However, if the resulting value of the code In this example the output is just plain text. However, if the resulting value of the code
block can be displayed as an image (png or jpeg) Literate will include the image block can be displayed as an image (image/png or image/jpeg), HTML (text/html) or markdown
representation of the output. (text/markdown) Literate will include the richest representation of the output.
!!! note !!! note
Since Documenter executes and captures results of `@example` block it is not necessary Since Documenter executes and captures results of `@example` block it is not necessary
to use `execute=true` for markdown output that is meant to be used as input to to use `execute=true` for markdown output that is meant to be used as input to
Documenter. Documenter.
!!! compat "Literate 2.4"
Code execution of markdown output requires at least Literate version 2.4.
See the section about [Configuration](@ref) for more information about how to configure the See the section about [Configuration](@ref) for more information about how to configure the
behavior and resulting output of [`Literate.markdown`](@ref). behavior and resulting output of [`Literate.markdown`](@ref).
@ -74,20 +77,16 @@ Literate.markdown
### Markdown flavors ### Markdown flavors
Literate supports different "flavors" to the markdown output. To specify a flavor pass the Literate can output markdown in different flavors. The flavor is specified using the
`flavor` keyword argument to [`Literate.markdown`](@ref). The default flavor `flavor` keyword argument. The following flavors are currently supported:
(`Literate.DefaultFlavor`) is the Documenter compatible output used throughout most examples.
Another supported flavor is `Literate.FranklinFlavor` for output compatible with the
[Franklin.jl](https://franklinjl.org/) static site generator. Currently the only difference
is that the Franklin flavor supports `text/html` MIME output when executing the markdown
file, e.g. with
```julia
Literate.markdown(input, output; execute=true, flavor=Literate.FranklinFlavor())
```
!!! compat "Literate 2.9"
The Franklin flavor requires at least Literate version 2.9.
## [**4.2.** Notebook Output](@id Notebook-Output) - `flavor = Literate.DocumenterFlavor()` this is the default flavor and the output is
meant to be used as input to [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).
- `flavor = Literate.FranklinFlavor()` this outputs markdown meant to be used as input
to [Franklin.jl](https://franklinjl.org/).
## [**4.2.** Notebook output](@id Notebook-output)
Notebook output is generated by [`Literate.notebook`](@ref). The (default) notebook output Notebook output is generated by [`Literate.notebook`](@ref). The (default) notebook output
of the source snippet can be seen here: [notebook.ipynb](generated/notebook.ipynb). of the source snippet can be seen here: [notebook.ipynb](generated/notebook.ipynb).
@ -136,7 +135,7 @@ y = 2//5
# For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html) # For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
``` ```
## [**4.3.** Script Output](@id Script-Output) ## [**4.3.** Script output](@id Script-output)
Script output is generated by [`Literate.script`](@ref). The (default) script output of the Script output is generated by [`Literate.script`](@ref). The (default) script output of the
source snippet above is as follows: source snippet above is as follows:
@ -166,9 +165,6 @@ The behavior of [`Literate.markdown`](@ref), [`Literate.notebook`](@ref) and
ways to do this; pass `config::Dict` as a keyword argument, or pass individual ways to do this; pass `config::Dict` as a keyword argument, or pass individual
keyword arguments. keyword arguments.
!!! compat "Literate 2.2"
Passing configuration as a dictionary requires at least Literate version 2.2.
!!! note "Configuration precedence" !!! note "Configuration precedence"
Individual keyword arguments take precedence over the `config` dictionary, so for e.g. Individual keyword arguments take precedence over the `config` dictionary, so for e.g.
`Literate.markdown(...; config = Dict("name" => "hello"), name = "world")` the `Literate.markdown(...; config = Dict("name" => "hello"), name = "world")` the

2
docs/src/pipeline.md
Unescape View File

@ -20,7 +20,7 @@ internal processing. Next, line filtering is performed, see [Filtering Lines](@r
meaning that lines starting with `#md `, `#nb ` or `#jl ` are handled (either just meaning that lines starting with `#md `, `#nb ` or `#jl ` are handled (either just
the token itself is removed, or the full line, depending on the output target). the token itself is removed, or the full line, depending on the output target).
The last pre-processing step is to expand the convenience "macros" described The last pre-processing step is to expand the convenience "macros" described
in [Default Replacements](@ref) is expanded. in [Default replacements](@ref) is expanded.
## [**3.2.** Parsing](@id Parsing) ## [**3.2.** Parsing](@id Parsing)

2
docs/src/tips.md
Unescape View File

@ -1,4 +1,4 @@
# [**7.** Tips and Tricks](@id tips-and-tricks) # [**7.** Tips and tricks](@id tips-and-tricks)
This section lists some tips and tricks that might be useful for using This section lists some tips and tricks that might be useful for using
Literate. Literate.

4
examples/example.jl
Unescape View File

@ -43,7 +43,7 @@ y = 2//5
#nb # %% A slide [markdown] {"slideshow": {"slide_type": "fragment"}} #nb # %% A slide [markdown] {"slideshow": {"slide_type": "fragment"}}
# It is possible to filter out lines depending on the output using the # It is possible to filter out lines depending on the output using the
# `#md`, `#nb`, `#jl` and `#src` tags (see [Filtering Lines](@ref)): # `#md`, `#nb`, `#jl` and `#src` tags (see [Filtering lines](@ref)):
#md # - This line starts with `#md` and is thus only visible in the markdown output. #md # - This line starts with `#md` and is thus only visible in the markdown output.
#nb # - This line starts with `#nb` and is thus only visible in the notebook output. #nb # - This line starts with `#nb` and is thus only visible in the notebook output.
#jl # - This line starts with `#jl` and is thus only visible in the script output. #jl # - This line starts with `#jl` and is thus only visible in the script output.
@ -65,7 +65,7 @@ x + y
x * y x * y
#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
# ### Output Capturing # ### Output capturing
# Code chunks are by default placed in Documenter `@example` blocks in the generated # 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 # 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 # building the docs. In notebooks the output is captured in output cells, if the

24
src/Literate.jl
Unescape View File

@ -13,6 +13,8 @@ import .IJulia
abstract type AbstractFlavor end abstract type AbstractFlavor end
struct DefaultFlavor <: AbstractFlavor end struct DefaultFlavor <: AbstractFlavor end
struct DocumenterFlavor <: AbstractFlavor end
struct FranklinFlavor <: AbstractFlavor end
# # Some simple rules: # # Some simple rules:
# #
@ -229,7 +231,7 @@ function create_configuration(inputfile; user_config, user_kwargs, type=nothing)
cfg["execute"] = type === :md ? false : true cfg["execute"] = type === :md ? false : true
cfg["codefence"] = get(user_config, "documenter", true) && !get(user_config, "execute", cfg["execute"]) ? cfg["codefence"] = get(user_config, "documenter", true) && !get(user_config, "execute", cfg["execute"]) ?
("````@example $(get(user_config, "name", cfg["name"]))" => "````") : ("````julia" => "````") ("````@example $(get(user_config, "name", cfg["name"]))" => "````") : ("````julia" => "````")
cfg["flavor"] = DefaultFlavor() cfg["flavor"] = type === (:md) ? DocumenterFlavor() : DefaultFlavor()
# Guess the package (or repository) root url # Guess the package (or repository) root url
edit_commit = "master" # TODO: Make this configurable like Documenter? edit_commit = "master" # TODO: Make this configurable like Documenter?
deploy_branch = "gh-pages" # TODO: Make this configurable like Documenter? deploy_branch = "gh-pages" # TODO: Make this configurable like Documenter?
@ -380,9 +382,6 @@ end
Generate a plain script file from `inputfile` and write the result to `outputdir`. Generate a plain script file from `inputfile` and write the result to `outputdir`.
!!! compat "Literate 2.5"
Default output directory `pwd` requires at least Literate version 2.5.
See the manual section on [Configuration](@ref) for documentation See the manual section on [Configuration](@ref) for documentation
of possible configuration with `config` and other keyword arguments. of possible configuration with `config` and other keyword arguments.
""" """
@ -416,18 +415,12 @@ function script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
end end
# struct Documenter <: Flavor end # TODO: Use this instead of documenter=true?
struct FranklinFlavor <: AbstractFlavor end
""" """
Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...) Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)
Generate a markdown file from `inputfile` and write the result Generate a markdown file from `inputfile` and write the result
to the directory `outputdir`. to the directory `outputdir`.
!!! compat "Literate 2.5"
Default output directory `pwd` requires at least Literate version 2.5.
See the manual section on [Configuration](@ref) for documentation See the manual section on [Configuration](@ref) for documentation
of possible configuration with `config` and other keyword arguments. of possible configuration with `config` and other keyword arguments.
""" """
@ -491,10 +484,12 @@ function execute_markdown!(io::IO, sb::Module, block::String, outputdir;
# issue #144: quadruple backticks allow for triple backticks in the output # issue #144: quadruple backticks allow for triple backticks in the output
plain_fence = "\n````\n" => "\n````" plain_fence = "\n````\n" => "\n````"
if r !== nothing && !REPL.ends_with_semicolon(block) if r !== nothing && !REPL.ends_with_semicolon(block)
if flavor isa FranklinFlavor && showable(MIME("text/html"), r) if (flavor isa FranklinFlavor || flavor isa DocumenterFlavor) &&
write(io, "\n~~~\n") showable(MIME("text/html"), r)
htmlfence = flavor isa FranklinFlavor ? ("~~~" => "~~~") : ("```@raw html" => "```")
write(io, "\n", htmlfence.first, "\n")
Base.invokelatest(show, io, MIME("text/html"), r) Base.invokelatest(show, io, MIME("text/html"), r)
write(io, "\n~~~\n") write(io, "\n", htmlfence.second, "\n")
return return
end end
for (mime, ext) in [(MIME("image/png"), ".png"), (MIME("image/jpeg"), ".jpeg")] for (mime, ext) in [(MIME("image/png"), ".png"), (MIME("image/jpeg"), ".jpeg")]
@ -545,9 +540,6 @@ line_is_nbmeta(line) = startswith(line, "%% ")
Generate a notebook from `inputfile` and write the result to `outputdir`. Generate a notebook from `inputfile` and write the result to `outputdir`.
!!! compat "Literate 2.5"
Default output directory `pwd` requires at least Literate version 2.5.
See the manual section on [Configuration](@ref) for documentation See the manual section on [Configuration](@ref) for documentation
of possible configuration with `config` and other keyword arguments. of possible configuration with `config` and other keyword arguments.
""" """

11
test/runtests.jl
Unescape View File

@ -696,6 +696,8 @@ end end
# execute # execute
write(inputfile, """ write(inputfile, """
using DisplayAs
#-
1+1 1+1
#- #-
[1 2; 3 4] [1 2; 3 4]
@ -712,7 +714,10 @@ end end
Base.show(io::IO, mime::MIME"text/markdown", ::MD) = print(io, "# " * "MD") Base.show(io::IO, mime::MIME"text/markdown", ::MD) = print(io, "# " * "MD")
Base.show(io::IO, mime::MIME"text/html", ::MD) = Base.show(io::IO, mime::MIME"text/html", ::MD) =
print(io, "<h1>" * "MD" * "</h1>") print(io, "<h1>" * "MD" * "</h1>")
MD() #-
DisplayAs.MD(MD())
#-
DisplayAs.HTML(MD())
#- #-
print("hello"); print(stdout, ", "); print(stderr, "world") print("hello"); print(stdout, ", "); print(stderr, "world")
#- #-
@ -733,7 +738,7 @@ end end
@test occursin(r"!\[\]\(\d+\.png\)", markdown) # image/png @test occursin(r"!\[\]\(\d+\.png\)", markdown) # image/png
@test occursin(r"!\[\]\(\d+\.jpeg\)", markdown) # image/jpeg @test occursin(r"!\[\]\(\d+\.jpeg\)", markdown) # image/jpeg
@test occursin("# MD", markdown) # text/markdown @test occursin("# MD", markdown) # text/markdown
@test !occursin("~~~\n<h1>MD</h1>\n~~~", markdown) # text/html @test occursin("```@raw html\n<h1>MD</h1>\n```", markdown) # text/html
@test occursin("```\nhello, world\n```", markdown) # stdout/stderr @test occursin("```\nhello, world\n```", markdown) # stdout/stderr
@test occursin("```\n42\n```", markdown) # result over stdout/stderr @test occursin("```\n42\n```", markdown) # result over stdout/stderr
@test !occursin("246", markdown) # empty output because trailing ; @test !occursin("246", markdown) # empty output because trailing ;
@ -742,7 +747,7 @@ end end
# FranklinFlavor # FranklinFlavor
Literate.markdown(inputfile, outdir; execute=true, flavor=Literate.FranklinFlavor()) Literate.markdown(inputfile, outdir; execute=true, flavor=Literate.FranklinFlavor())
markdown = read(joinpath(outdir, "inputfile.md"), String) markdown = read(joinpath(outdir, "inputfile.md"), String)
@test !occursin("# MD", markdown) # text/markdown @test occursin("# MD", markdown) # text/markdown
@test occursin("~~~\n<h1>MD</h1>\n~~~", markdown) # text/html @test occursin("~~~\n<h1>MD</h1>\n~~~", markdown) # text/html
# verify that inputfile exists # verify that inputfile exists

Write Preview
Loading…
Cancel
Save