Last active
April 11, 2018 06:28
-
-
Save mortenpi/31f9d38fb6c7bc5d858ac5b86c4fb039 to your computer and use it in GitHub Desktop.
Some speculation about the future of Documenter's user-facing API.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# This would be make.jl. | |
# | |
# The user can then interact with this configuration through the | |
# command line: | |
# | |
# julia docs/make.jl doctest | |
# julia docs/make.jl build --html | |
# julia docs/make.jl deploy --latex --html | |
using Documenter, DocumenterLaTeX | |
docs = Document( | |
modules = [Documenter], | |
sitename = "Documenter.jl", # sitename is not necessarily a good name for this... | |
authors = "Michael Hatherly, Morten Piibeleht, and contributors.", | |
pages = [ ... ], | |
) | |
htmlwriter = Writers.HTML( | |
assets = ["assets/favicon.ico"], | |
pretty_urls = true, | |
canonical_url = "https://juliadocs.github.io/Documenter.jl/stable/", | |
) | |
pdfwriter = DocumenterLaTeX.LaTeX( | |
output_filename = "documenter.pdf", | |
) | |
deploy = DeployGitHub( | |
repo = "github.com/JuliaDocs/Documenter.jl.git", | |
branch = "gh-pages", | |
) | |
Documenter.run(ARGS, docs, htmlwriter, pdfwriter, deploy) | |
# All the objects created here (docs, *writer, deploy) would be descriptive only. | |
# It's up to run() to actually build something coherent out of them. | |
# | |
# Under the hood, run() would look something like this (extremely sketchy): | |
blueprint = parse(docs) | |
if "--doctest" doctest(blueprint) end | |
document = build(blueprint) | |
rendered_html = render(htmlwriter, deploy, document; output_dir=tmpdir()) | |
rendered_pdf = render(pdfwriter, deploy, document; output_dir=rendered_html.output_dir) | |
install(rendered_html, deploy) | |
# The reason render() needs both the writer and deploy is because deployment details can | |
# affect how a page is rendered (e.g. repo URL). | |
# | |
# If the user wants more control over the build steps, then they can also write custom | |
# run()-like steps in make.jl, instead of using run(). | |
# Finally, this is a bit speculative, but we could also provide a | |
# mechanism to read in the configuration: | |
# | |
# Documenter.loadconfig(Pkg.dir("Documenter", "docs/make.jl")) | |
# | |
# This would eval() the contents of `make.jl` (probably in a submodule), | |
# overriding Documenter.run() in a way that nothing gets run and returns an object | |
# that the | |
# | |
# This way the user can e.g. run doctests during testing. In `runtests.jl`: | |
using Documenter | |
docscfg = Documenter.loadconfig(Pkg.dir("Documenter", "docs/make.jl")) | |
@test Documenter.doctest(docscfg) | |
# Would basically be equivalent to `julia docs/make.jl --doctest` |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment