You use Literate as a sort of preprocessor to produce the .md file, which you then include in your docs exactly as you would include a .md file that you had written out manually. Then, if you want a PDF version, you can just follow these instructions to build via LaTeX.
I would suggest building up to a full PDF version. First, make sure you can generate the HTML, since that’s the most basic way to use Documenter, and will make sure you have the Literate+Documenter things set up properly before trying to involve LaTeX. I’m not sure if this is the simplest way, but I think Documenter requires some basic structure, so I followed the guide and put the following in Example/src/Example.jl:
module Example
export func
"""
func(x)
Return double the number `x` plus `1`.
"""
func(x) = 2x + 1
end
I then put this in the Example/docs/src/index.md (because it’s mandatory for HTML output, though not for LaTeX):
# Example.jl Documentation
```@docs
func(x)
```
I then put your file in Example/src/psm_test.jl, as well as the following in Example/docs/make.jl:
# I haven't made `Example` an actual package that can be installed, so I just do this:
push!(LOAD_PATH,"../src/")
using Documenter, Example, Literate
# Use Literate to convert `psm_test.jl` to markdown for Documenter
input_file = "../src/psm_test.jl"
output_directory = "src/"
Literate.markdown(input_file, output_directory; documenter=true, execute=false)
# Now make the docs with Documenter
makedocs(
sitename="My Documentation",
remotes=nothing, # Don't look for a git repo of the `Example` package; I haven't made one
draft=true, # Don't run the `@example` block; I don't have the necessary files, etc.
pages=[
"Introduction" => "index.md",
"PSM Test" => "psm_test.md",
],
)
Note that I’ve had to add some hacky lines in there because I didn’t make Example a real project. If you have a real project, install it into the docs project, and you can remove the LOAD_PATH and remotes lines. Also, since you’re evidently able to run the example, you should be able to delete the draft line — though again, I’d only do that after getting it running in draft mode.
Then, from the Examples/docs directory, I run
julia --project make.jl
(You may have to install Documenter and/or Literate in the docs project manually; I actually have both in my base project, so this just works for me.) This generates some warnings because I haven’t made this into an actual package, but the build succeeds, and I can
open build/psm_test/index.html
which has the desired docs.
Next, just build the .tex file itself because you might not have all the LaTeX stuff installed, or Documenter might not know where to find it, but the .tex file should build successfully anyway. To do so, just add
format=Documenter.LaTeX(platform="none"),
to the makedocs call and run again. This time, you should find Example/docs/build/MyDocumentation.tex containing the complete docs. (You can remove the index.md line now, if you want.)
Finally, if that looks sensible, you can have Documenter actually call LaTeX by removing platform="none" from the line above, so that it now looks like
format=Documenter.LaTeX(),
And you should have Example/docs/build/MyDocumentation.pdf.
If any of these steps fails, please feel free to ask more specific questions.
