From e7fae2459e4d03778f3cbd5236c636e3ae4e42ca Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Thu, 23 Apr 2020 14:56:46 +0200 Subject: [PATCH] Misc doc updates; links, css, changelog, compat notes etc. --- CHANGELOG.md | 6 ++++++ README.md | 10 +++++----- docs/Manifest.toml | 26 +++++++++++++++++--------- docs/make.jl | 1 + docs/src/assets/custom.css | 8 ++++++-- docs/src/fileformat.md | 9 +++++++++ docs/src/outputformats.md | 7 +++++-- examples/README.jl | 10 +++++----- src/Literate.jl | 2 +- 9 files changed, 55 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 22ce98a..209f895 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Literate.jl changelog +## Version `v2.4` + +* ![Feature][badge-feature] Markdown output can now be executed and the result included + in the output by pasing `execute=true` to `Literate.markdown.` ([7e89fdb][7e89fdb]). + ## Version `v2.3` * ![Feature][badge-feature] Filter tokens `#md`, `#nb`, and `#jl`, as well as their negated @@ -59,6 +64,7 @@ [0f9e836]: https://github.com/fredrikekre/Literate.jl/commit/0f9e836d68f238becd3e193b22ebdad06e4d7ffa [4e71b15]: https://github.com/fredrikekre/Literate.jl/commit/4e71b159e5ce392c23e6f18116f96803191354c3 [b0806ed]: https://github.com/fredrikekre/Literate.jl/commit/b0806edb6707d03c73bcb0829e96be336229bbeb +[7e89fdb]: https://github.com/fredrikekre/Literate.jl/commit/7e89fdbffdfc56a08caee47287429b4611f85684 [badge-breaking]: https://img.shields.io/badge/BREAKING-red.svg [badge-deprecation]: https://img.shields.io/badge/deprecation-orange.svg diff --git a/README.md b/README.md index 27bab3f..6e53755 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Literate -| **Documentation** | **Build Status** | -|:--------------------------------------- |:----------------------------------------------------------------------------------------------- | -| [![][docs-stable-img]][docs-stable-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] | +| **Documentation** | **Build Status** | +|:------------------------- |:----------------------------------------------------------------------------------------------- | +| [![][docs-img]][docs-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] | Literate is a package for [Literate Programming](https://en.wikipedia.org/wiki/Literate_programming). The main purpose is to facilitate writing Julia examples/tutorials that can be included in @@ -24,8 +24,8 @@ using Literate Literate.markdown("examples/README.jl", "."; documenter=false) ``` -[docs-stable-img]: https://img.shields.io/badge/docs-stable%20release-blue.svg -[docs-stable-url]: https://fredrikekre.github.io/Literate.jl/stable/ +[docs-img]: https://img.shields.io/badge/docs-latest%20release-blue.svg +[docs-url]: https://fredrikekre.github.io/Literate.jl/ [travis-img]: https://travis-ci.org/fredrikekre/Literate.jl.svg?branch=master [travis-url]: https://travis-ci.org/fredrikekre/Literate.jl diff --git a/docs/Manifest.toml b/docs/Manifest.toml index 38cbf8f..d3e0dd8 100644 --- a/docs/Manifest.toml +++ b/docs/Manifest.toml @@ -34,9 +34,9 @@ version = "1.1.0" [[DataStructures]] deps = ["InteractiveUtils", "OrderedCollections"] -git-tree-sha1 = "73eb18320fe3ba58790c8b8f6f89420f0a622773" +git-tree-sha1 = "4dead20a1606a60292529023d6eac18a1ef6432e" uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8" -version = "0.17.11" +version = "0.17.12" [[Dates]] deps = ["Printf"] @@ -58,9 +58,11 @@ version = "0.8.1" [[Documenter]] deps = ["Base64", "Dates", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"] -git-tree-sha1 = "646ebc3db49889ffeb4c36f89e5d82c6a26295ff" +git-tree-sha1 = "d834190e7a8ae41b46eac249dbecd6dacc7c6160" +repo-rev = "master" +repo-url = "https://github.com/JuliaDocs/Documenter.jl.git" uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4" -version = "0.24.7" +version = "0.24.7+0.25-DEV" [[FFMPEG]] deps = ["FFMPEG_jll"] @@ -215,10 +217,10 @@ uuid = "995b91a9-d308-5afd-9ec6-746e21dbc043" version = "0.6.5" [[Plots]] -deps = ["Base64", "Contour", "Dates", "FFMPEG", "FixedPointNumbers", "GR", "GeometryTypes", "JSON", "LinearAlgebra", "Measures", "NaNMath", "Pkg", "PlotThemes", "PlotUtils", "Printf", "REPL", "Random", "RecipesBase", "Reexport", "Requires", "Showoff", "SparseArrays", "Statistics", "StatsBase", "UUIDs"] -git-tree-sha1 = "6c24a62e4b668100b45ba6610c7bd14697fe7743" +deps = ["Base64", "Contour", "Dates", "FFMPEG", "FixedPointNumbers", "GR", "GeometryTypes", "JSON", "LinearAlgebra", "Measures", "NaNMath", "Pkg", "PlotThemes", "PlotUtils", "Printf", "REPL", "Random", "RecipesBase", "RecipesPipeline", "Reexport", "Requires", "Showoff", "SparseArrays", "Statistics", "StatsBase", "UUIDs"] +git-tree-sha1 = "e975cd074ccc195285fea8ba5e9c0044ee8cb949" uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" -version = "1.0.3" +version = "1.0.9" [[Printf]] deps = ["Unicode"] @@ -237,6 +239,12 @@ git-tree-sha1 = "d352369b00094cadb43d694333b051b3d55abaf2" uuid = "3cdcf5f2-1ef4-517c-9805-6587b60abb01" version = "1.0.0" +[[RecipesPipeline]] +deps = ["Dates", "PlotUtils", "RecipesBase"] +git-tree-sha1 = "3d4ecb5aa24a8582a946a2cc0d2a65b085697750" +uuid = "01d81517-befc-4cb6-b9ec-a95719d0359c" +version = "0.1.3" + [[Reexport]] deps = ["Pkg"] git-tree-sha1 = "7b1d07f411bc8ddb7977ec7f377b97b158514fe0" @@ -286,9 +294,9 @@ uuid = "10745b16-79ce-11e8-11f9-7d13ad32a3b2" [[StatsBase]] deps = ["DataAPI", "DataStructures", "LinearAlgebra", "Missings", "Printf", "Random", "SortingAlgorithms", "SparseArrays", "Statistics"] -git-tree-sha1 = "19bfcb46245f69ff4013b3df3b977a289852c3a1" +git-tree-sha1 = "a6102b1f364befdb05746f386b67c6b7e3262c45" uuid = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91" -version = "0.32.2" +version = "0.33.0" [[Test]] deps = ["Distributed", "InteractiveUtils", "Logging", "Random"] diff --git a/docs/make.jl b/docs/make.jl index 84a1b2b..f8a42dc 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -48,6 +48,7 @@ makedocs( format = Documenter.HTML( assets = ["assets/custom.css", "assets/favicon.ico"], prettyurls = haskey(ENV, "GITHUB_ACTIONS"), + canonical = "https://fredrikekre.github.io/Literate.jl/v2", ), modules = [Literate], sitename = "Literate.jl", diff --git a/docs/src/assets/custom.css b/docs/src/assets/custom.css index f59c104..9bac5b4 100644 --- a/docs/src/assets/custom.css +++ b/docs/src/assets/custom.css @@ -1,3 +1,7 @@ -nav.toc .logo { - max-height: 12em; +div#documenter .docs-sidebar .docs-logo > img { + max-height: 10em; } +div#documenter .docs-sidebar .docs-package-name { + padding-top: 1rem; +} +/*1.0rem 0 0.5rem 0;*/ diff --git a/docs/src/fileformat.md b/docs/src/fileformat.md index 8ec4723..db82522 100644 --- a/docs/src/fileformat.md +++ b/docs/src/fileformat.md @@ -59,6 +59,9 @@ certain lines: Lines *starting* or *ending* with one of these tokens are filtered out in the [preprocessing step](@ref Pre-processing). +!!! compat "Literate 2.3" + Filter tokens at the end of the line requires at least Literate version 2.3. + !!! tip 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. @@ -124,3 +127,9 @@ The following convenience "macros"/source placeholders are always expanded: ``` This variable is automatically determined on Travis CI, GitHub Actions and GitLab CI, 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. diff --git a/docs/src/outputformats.md b/docs/src/outputformats.md index 0f1a616..939b861 100644 --- a/docs/src/outputformats.md +++ b/docs/src/outputformats.md @@ -50,8 +50,8 @@ representation of the output. to use `execute=true` for markdown output that is meant to be used as input to Documenter. -!!! compat "Literate 2.3" - Code execution of markdown output requires at least Literate version 2.3. +!!! 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 behavior and resulting output of [`Literate.markdown`](@ref). @@ -139,6 +139,9 @@ The behavior of [`Literate.markdown`](@ref), [`Literate.notebook`](@ref) and ways to do this; pass `config::Dict` as a keyword argument, or pass individual keyword arguments. +!!! compat "Literate 2.2" + Passing configuration as a dictionary requires at least Literate version 2.2. + !!! note "Configuration precedence" Individual keyword arguments takes precedence over the `config` dictionary, so for e.g. `Literate.markdown(...; config = Dict("name" => "hello"), name = "world")` the diff --git a/examples/README.jl b/examples/README.jl index 9bdd21d..e0227ad 100644 --- a/examples/README.jl +++ b/examples/README.jl @@ -1,8 +1,8 @@ # # Literate # -# | **Documentation** | **Build Status** | -# |:--------------------------------------- |:----------------------------------------------------------------------------------------------- | -# | [![][docs-stable-img]][docs-stable-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] | +# | **Documentation** | **Build Status** | +# |:------------------------- |:----------------------------------------------------------------------------------------------- | +# | [![][docs-img]][docs-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] | # # Literate is a package for [Literate Programming](https://en.wikipedia.org/wiki/Literate_programming). # The main purpose is to facilitate writing Julia examples/tutorials that can be included in @@ -22,8 +22,8 @@ using Literate Literate.markdown("examples/README.jl", "."; documenter=false) -# [docs-stable-img]: https://img.shields.io/badge/docs-stable%20release-blue.svg -# [docs-stable-url]: https://fredrikekre.github.io/Literate.jl/stable/ +# [docs-img]: https://img.shields.io/badge/docs-latest%20release-blue.svg +# [docs-url]: https://fredrikekre.github.io/Literate.jl/ # # [travis-img]: https://travis-ci.org/fredrikekre/Literate.jl.svg?branch=master # [travis-url]: https://travis-ci.org/fredrikekre/Literate.jl diff --git a/src/Literate.jl b/src/Literate.jl index 7b64097..06973e3 100644 --- a/src/Literate.jl +++ b/src/Literate.jl @@ -288,7 +288,7 @@ See the manual section about [Configuration](@ref) for more information. | `documenter` | Boolean signaling that the source contains Documenter.jl elements. | `true` | See [Interaction with Documenter](@ref Interaction-with-Documenter). | | `credit` | Boolean for controlling the addition of `This file was generated with Literate.jl ...` to the bottom of the page. If you find Literate.jl useful then feel free to keep this. | `true` | | | `keep_comments` | When `true`, keeps markdown lines as comments in the output script. | `false` | Only applicable for `Literate.script`. | -| `execute` | Whether to execute and capture the output. | `true` (notebook), `false` (markdown) | Only applicable for `Literate.notebook` and `Literate.markdown`. For markdown this requires at least Literate 2.3. | +| `execute` | Whether to execute and capture the output. | `true` (notebook), `false` (markdown) | Only applicable for `Literate.notebook` and `Literate.markdown`. For markdown this requires at least Literate 2.4. | | `codefence` | Pair containing opening and closing fence for wrapping code blocks. | `````"```julia" => "```"````` | If `documenter` is `true` the default is `````"```@example"=>"```"`````. | | `devurl` | URL for "in-development" docs. | `"dev"` | See [Documenter docs](https://juliadocs.github.io/Documenter.jl/). Unused if `repo_root_url`/`nbviewer_root_url`/`binder_root_url` are set. | | `repo_root_url` | URL to the root of the repository. | - | Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for `@__REPO_ROOT_URL__`. |