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

perform requested changes

pull/35/head
George Datseris 7 years ago committed by GitHub
parent
de783e221c
commit
73b546055f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 20 additions and 25 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. 45
      docs/src/customprocessing.md

45
docs/src/customprocessing.md
Unescape View File

@ -22,7 +22,7 @@ is given the content `String` just before writing it to the output file, but for
notebook output `postprocess` is given the dictionary representing the notebook, notebook output `postprocess` is given the dictionary representing the notebook,
since, in general, this is more useful. since, in general, this is more useful.
## Example: Adding current date ### Example: Adding current date
As an example, lets say we want to splice the date of generation into the output. As an example, lets say we want to splice the date of generation into the output.
We could of course update our source file before generating the docs, but we could We could of course update our source file before generating the docs, but we could
instead use a `preprocess` function that splices the date into the source for us. instead use a `preprocess` function that splices the date into the source for us.
@ -47,43 +47,36 @@ now simply give this function to the generator, for example:
Literate.markdown("input.jl", "outputdir"; preprocess = update_date) Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
``` ```
## Example: Replacing `include` calls with included code ### Example: Replacing `include` calls with included code
Let's say that we have some individual example files `file1, file2, ...` etc. Let's say that we have some individual example files `file1, file2, ...` etc.
that are _runnable_ and also following the style of Literate. These files could be for example used in the test suite of your package. that are _runnable_ and also following the style of Literate. These files could be for example used in the test suite of your package.
We want to group them all into a single page in our documentation, but we We want to group them all into a single page in our documentation, but we
do not want to copy paste the content of `file1, ...` for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation. do not want to copy paste the content of `file1, ...` for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
A very easy way to do this is using `preprocess` to interchange `include` statements with file content. First, create a runnable `.jl` following the format of Literate (the following example comes from the documentation of the Julia package [`TimeseriesPrediction`](https://github.com/JuliaDynamics/TimeseriesPrediction.jl), which uses this approach to create some pages) A very easy way to do this is using `preprocess` to interchange `include` statements with file content. First, create a runnable `.jl` following the format of Literate
```julia ```julia
# # Spatio-Temporal Prediction Examples # # Replace includes
# In this page we are simply running files from the # This is an example to replace `include` calls with the actual file content.
# `examples` folder of the `TimeseriesPrediction` package.
# ## Temporal Prediction: Kuramoto-Sivashinsky include("file1.jl")
# *(this requires `FFTW` to be installed)*
include("1Dfield_temporalprediction.jl") # Cool, we just saw the result of the above code snippet. Here is one more:
# ## Cross Prediction: Barkley Model include("file2.jl")
include("2Dfield_crossprediction.jl")
# ## Temporal Prediction: Periodic Nonlinear Barkley Model
include("2Dfield_temporalprediction.jl")
``` ```
Let's say we have saved this file as `stexamples.jl`.
Let's say we have saved this file as `examples.jl`.
Then, you want to properly define a pre-processing function: Then, you want to properly define a pre-processing function:
```julia ```julia
function replace_includes(str) function replace_includes(str)
included = ["1Dfield_temporalprediction.jl", included = ["file1.jl", "file2.jl"]
"2Dfield_crossprediction.jl", "2Dfield_temporalprediction.jl"]
# Here path loads the files from their proper directory, # Here the path loads the files from their proper directory,
# which may not be the directory of the `stexamples.jl` file! # which may not be the directory of the `examples.jl` file!
path = dirname(dirname(pathof(TimeseriesPrediction)))*"/examples/" path = "directory/to/example/files/"
for ex in included for ex in included
content = read(path*ex, String) content = read(path*ex, String)
@ -96,8 +89,10 @@ end
Finally, you simply pass this function to e.g. [`Literate.markdown`](@ref) as Finally, you simply pass this function to e.g. [`Literate.markdown`](@ref) as
```julia ```julia
Literate.markdown("src/tsprediction/stexamples.jl", "src/tsprediction/"; Literate.markdown("examples.jl", "path/to/save/markdown";
name = "stexamples", preprocess = replace_includes) name = "markdown_file_name", preprocess = replace_includes)
``` ```
and you will see that in the final output file (here `stexamples.md`) the `include` and you will see that in the final output file (here `markdown_file_name.md`) the `include`
statements are replaced with the actual code to be included! statements are replaced with the actual code to be included!
This approach is used for example in the documentation of the Julia package [`TimeseriesPrediction`](https://github.com/JuliaDynamics/TimeseriesPrediction.jl), see [here](https://github.com/JuliaDynamics/DynamicalSystems.jl/blob/master/docs/src/tsprediction/stexamples.jl) and [here for the generating script](https://github.com/JuliaDynamics/DynamicalSystems.jl/blob/master/docs/make.jl#L11-L29)

Write Preview
Loading…
Cancel
Save