diff --git a/.gitignore b/.gitignore index dd48bf4..091c3d4 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,6 @@ Manifest.toml # As should .vscode! .vscode + +# Python virtual environments +venv diff --git a/docs/.gitignore b/docs/.gitignore index 1f89788..a7e65ab 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,10 +1,3 @@ -build/ -site/ -.quarto /.quarto/ -venv -_book _site -_manuscript -*.pdf -*.html \ No newline at end of file +.quarto \ No newline at end of file diff --git a/docs/Project.toml b/docs/Project.toml index 6df8fb9..8911b05 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,3 @@ [deps] AstrodynamicalModels = "4282b555-f590-4262-b575-3e516e1493a7" -Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" -Quarto = "d7167be5-f61b-4dc9-b75c-ab62374668c5" QuartoDocumenter = "73f83fcb-c367-40db-89b6-8fd94701aaf2" diff --git a/docs/_extensions/quarto-ext/latex-environment/_extension.yml b/docs/_extensions/quarto-ext/latex-environment/_extension.yml deleted file mode 100644 index 2f55b2f..0000000 --- a/docs/_extensions/quarto-ext/latex-environment/_extension.yml +++ /dev/null @@ -1,9 +0,0 @@ -title: LaTeX Environment -author: Posit Software, PBC -version: 1.2.1 -quarto-required: ">=1.3" -contributes: - filters: - - latex-environment.lua - format: - pdf: default diff --git a/docs/_extensions/quarto-ext/latex-environment/latex-environment.lua b/docs/_extensions/quarto-ext/latex-environment/latex-environment.lua deleted file mode 100644 index 389a25f..0000000 --- a/docs/_extensions/quarto-ext/latex-environment/latex-environment.lua +++ /dev/null @@ -1,150 +0,0 @@ --- environment.lua --- Copyright (C) 2020 by RStudio, PBC - -local classEnvironments = pandoc.MetaMap({}) -local classCommands = pandoc.MetaMap({}) - --- helper that identifies arrays -local function tisarray(t) - local i = 0 - for _ in pairs(t) do - i = i + 1 - if t[i] == nil then return false end - end - return true -end - --- reads the environments -local function readEnvironments(meta) - local env = meta['environments'] - if env ~= nil then - if tisarray(env) then - -- read an array of strings - for i, v in ipairs(env) do - local value = pandoc.utils.stringify(v) - classEnvironments[value] = value - end - else - -- read key value pairs - for k, v in pairs(env) do - local key = pandoc.utils.stringify(k) - local value = pandoc.utils.stringify(v) - classEnvironments[key] = value - end - end - end -end - -local function readCommands(meta) - local env = meta['commands'] - if env ~= nil then - if tisarray(env) then - -- read an array of strings - for i, v in ipairs(env) do - local value = pandoc.utils.stringify(v) - classCommands[value] = value - end - else - -- read key value pairs - for k, v in pairs(env) do - local key = pandoc.utils.stringify(k) - local value = pandoc.utils.stringify(v) - classCommands[key] = value - end - end - end -end - -local function readEnvsAndCommands(meta) - readEnvironments(meta) - readCommands(meta) -end - --- use the environments from metadata to --- emit a custom environment for latex -local function writeEnvironments(divEl) - if quarto.doc.is_format("latex") then - for k, v in pairs(classEnvironments) do - if divEl.attr.classes:includes(k) then - -- process this into a latex environment - local beginEnv = '\\begin' .. '{' .. v .. '}' - local endEnv = '\n\\end{' .. v .. '}' - - -- check if custom options or arguments are present - -- and add them to the environment accordingly - local opts = divEl.attr.attributes['options'] - if opts then - beginEnv = beginEnv .. '[' .. opts .. ']' - end - - local args = divEl.attr.attributes['arguments'] - if args then - beginEnv = beginEnv .. '{' .. args .. '}' - end - - -- if the first and last div blocks are paragraphs then we can - -- bring the environment begin/end closer to the content - if #divEl.content > 0 and divEl.content[1].t == "Para" and divEl.content[#divEl.content].t == "Para" then - table.insert(divEl.content[1].content, 1, pandoc.RawInline('tex', beginEnv .. "\n")) - table.insert(divEl.content[#divEl.content].content, pandoc.RawInline('tex', "\n" .. endEnv)) - else - table.insert(divEl.content, 1, pandoc.RawBlock('tex', beginEnv)) - table.insert(divEl.content, pandoc.RawBlock('tex', endEnv)) - end - return divEl - end - end - end -end - -local function buildCommandArgs(opts, format) - local function wrap(o) - return string.format(format, o) - end - local t = pandoc.List() - for str in string.gmatch(opts, "([^"..",".."]+)") do - t:insert(str) - end - return table.concat(t:map(wrap), "") -end - --- use the environments from metadata to --- emit a custom environment for latex -local function writeCommands(spanEl) - if quarto.doc.is_format("latex") then - for k, v in pairs(classCommands) do - if spanEl.attr.classes:includes(k) then - - -- resolve the begin command - local beginCommand = '\\' .. pandoc.utils.stringify(v) - local opts = spanEl.attr.attributes['options'] - local args = spanEl.attr.attributes['arguments'] - if opts then - beginCommand = beginCommand .. buildCommandArgs(opts, "[%s]") - end - if args then - beginCommand = beginCommand .. buildCommandArgs(args, "{%s}") - end - - local beginCommandRaw = pandoc.RawInline('latex', beginCommand .. '{') - - -- the end command - local endCommandRaw = pandoc.RawInline('latex', '}') - - -- attach the raw inlines to the span contents - local result = spanEl.content - table.insert(result, 1, beginCommandRaw) - table.insert(result, endCommandRaw) - - return result - end - end - end -end - --- Run in two passes so we process metadata --- and then process the divs -return { - { Meta = readEnvsAndCommands }, - { Div = writeEnvironments, Span = writeCommands } -} diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 44210f7..2472133 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -1,24 +1,40 @@ project: - type: book + type: website -book: - title: "Doc" - author: "Norah Jones" - date: "4/7/2024" - chapters: - - index.qmd - - intro.qmd - - summary.qmd - - references.qmd +website: + title: "QuartoDocumenter.jl" + bread-crumbs: false + navbar: + left: + - href: index.qmd + text: Home + sidebar: + search: true + contents: + - section: "Overview" + contents: + - index.qmd + - section: "Examples" + contents: + - examples/index.qmd + - section: "Reference" + contents: + - reference/index.qmd -bibliography: references.bib +execute: + cache: false + freeze: false + echo: true + output: true + warning: false format: html: - theme: cosmo - pdf: - documentclass: article - shift-heading-level-by: 1 + theme: + light: lightly + dark: darkly + css: styles.css + toc: true diff --git a/docs/cover.png b/docs/cover.png deleted file mode 100644 index e1f5bc6..0000000 Binary files a/docs/cover.png and /dev/null differ diff --git a/docs/examples/index.qmd b/docs/examples/index.qmd new file mode 100644 index 0000000..1b976a9 --- /dev/null +++ b/docs/examples/index.qmd @@ -0,0 +1 @@ +# Examples \ No newline at end of file diff --git a/docs/index.qmd b/docs/index.qmd index 15f5f60..15c8bc2 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -1,11 +1,8 @@ -# Preface {.unnumbered} +--- +title: "QuartoDocumenter.jl" +sidebar: true +--- -This is a Quarto book. +This is a Quarto website. -To learn more about Quarto books visit . - - -```{julia} -using QuartoDocumenter, AstrodynamicalModels -QuartoDocumenter.autodoc(AstrodynamicalModels) -``` \ No newline at end of file +To learn more about Quarto websites visit . diff --git a/docs/intro.qmd b/docs/intro.qmd deleted file mode 100644 index efcf172..0000000 --- a/docs/intro.qmd +++ /dev/null @@ -1,5 +0,0 @@ -# Introduction - -This is a book created from markdown and executable code. - -See @knuth84 for additional discussion of literate programming. diff --git a/docs/quarto/index.qmd b/docs/quarto/index.qmd new file mode 100644 index 0000000..fede399 --- /dev/null +++ b/docs/quarto/index.qmd @@ -0,0 +1 @@ +# Quarto \ No newline at end of file diff --git a/docs/reference/index.qmd b/docs/reference/index.qmd new file mode 100644 index 0000000..47fe5ca --- /dev/null +++ b/docs/reference/index.qmd @@ -0,0 +1,7 @@ +# Reference + +```{julia} +#| echo: false +using QuartoDocumenter, AstrodynamicalModels +QuartoDocumenter.autodoc(AstrodynamicalModels) +``` \ No newline at end of file diff --git a/docs/references.bib b/docs/references.bib deleted file mode 100644 index 0220dbd..0000000 --- a/docs/references.bib +++ /dev/null @@ -1,19 +0,0 @@ -@article{knuth84, - author = {Knuth, Donald E.}, - title = {Literate Programming}, - year = {1984}, - issue_date = {May 1984}, - publisher = {Oxford University Press, Inc.}, - address = {USA}, - volume = {27}, - number = {2}, - issn = {0010-4620}, - url = {https://doi.org/10.1093/comjnl/27.2.97}, - doi = {10.1093/comjnl/27.2.97}, - journal = {Comput. J.}, - month = may, - pages = {97–111}, - numpages = {15} -} - - diff --git a/docs/references.qmd b/docs/references.qmd deleted file mode 100644 index 925f7c4..0000000 --- a/docs/references.qmd +++ /dev/null @@ -1,4 +0,0 @@ -# References {.unnumbered} - -::: {#refs} -::: diff --git a/docs/styles.css b/docs/styles.css new file mode 100644 index 0000000..2ddf50c --- /dev/null +++ b/docs/styles.css @@ -0,0 +1 @@ +/* css styles */ diff --git a/docs/summary.qmd b/docs/summary.qmd deleted file mode 100644 index b450ab7..0000000 --- a/docs/summary.qmd +++ /dev/null @@ -1,3 +0,0 @@ -# Summary - -In summary, this book has no content whatsoever. diff --git a/src/QuartoDocumenter.jl b/src/QuartoDocumenter.jl index 95253e8..19dead9 100644 --- a/src/QuartoDocumenter.jl +++ b/src/QuartoDocumenter.jl @@ -15,7 +15,7 @@ macro autodoc(lvalues...) end end -macro autodocs(lvalues) +macro autodoc(lvalues) return quote autodoc(@__MODULE__, $(lvalues)...) end @@ -27,12 +27,6 @@ function process_headers(markdown) for (index, item) in enumerate(markdown.content) if item isa Markdown.Header newlevel = min(level(item) + 3, 6) - if item.text isa AbstractVector - @info "Appending to item.text" - push!(item.text, " {.unnumbered} ") - elseif item.text isa AbstractString - item.text *= " {.unnumbered} " - end markdown.content[index] = Markdown.Header{newlevel}(item.text) elseif :content in propertynames(item) markdown.content[index] = process_headers(item) @@ -76,6 +70,12 @@ function process(markdown) ) end +""" +Return the documentation string associated with the provided name, with +substitutions to allow for compatibility with [Quarto](https://quarto.org). +""" +function doc end + function doc(mod::Module, sym::Symbol) parent = which(mod, sym) docmkd = copy(Base.Docs.doc(Docs.Binding(parent, sym))) @@ -83,25 +83,21 @@ function doc(mod::Module, sym::Symbol) end function doc(any::Any) - @info Base.Docs.doc(any) |> typeof docmkd = process( copy(Base.Docs.doc(any)) ) return Markdown.MD( - Markdown.parse(""":::{.callout appearance="simple"}"""), + Markdown.parse( + """ + ## `$(nameof(any))` + :::{.callout-note appearance="simple"} + """ + ), docmkd, - md":::" - ) -end - -function doc(mod::Module) - docmkd = process( - copy(Base.Docs.doc(mod)) - ) - - return Markdown.MD( - docmkd + md""" + ::: + """ ) end