2019-07-23 –, Elm A
Documenter compiles docstrings, code snippets, and Markdown pages into HTML or PDF documents and can automatically deploy them as websites, making it easy to create manuals for Julia packages that are immediately available to users. This talk explores what goes into making all of that happen.
Documenter can take Markdown files and inline docstrings and combine them into a manual for your Julia package. In addition, it can also run code snippets, verify that the output from code examples is up to date (doctesting) and upload the manual automatically to GitHub from a Travis CI build to be published as a website. Documenter is used by many Julia packages, and for generating Julia's own manual.
Behind the scenes, Documenter needs to (1) parse and represent Markdown documents, done via the Markdown standard library, (2) run code snippets embedded in the Markdown documents, (3) work with meta-information about functions and types, such as method signatures, and (4) fetch docstrings from your Julia code. Once all that is done, it compiles the result into the chosen output format -- a set of HTML pages or a PDF document.
The talk explores how Documenter goes from a make.jl script to a completely rendered and deployed manual. It should give existing users a glance into how Documenter works, but also provide a thorough overview of what is possible with Documenter to prospective new users.
Morten Piibeleht is a PhD student at Massey University, New Zealand, doing theory and computational work in the field of atomic physics and QED. In his spare time he is one of the maintainers of Documenter and the JuliaDocs organization.