Skip to content

Documenter

Lower Level Entities(Structs, methods etc.)

These are the objects on which nbdev's Documenter module was built. You can use it to extend nbdev but these are automtically used by Nbdev's internal engine to generate code files for you.

#noop
begin
f = joinpath("..", "Project.toml")
path = "https://github.com/sapal6/Nbdev.jl"
res = Dict("github_url" => "https://github.com/sapal6/Nbdev.jl")
end
------
Output
------


#noop
@test Common.getsetting(f, "settings") == res
------
Output
------


#noop
@test Common.getsettings(f, ["settings", "github_url"]) == res["github_url"]
------
Output
------

Section type

line(section::Section)–> Getter for accessing the underlying field line.

source

Example

section=Section("This is a test line")
------
Output
------
Any["Section", Any[(:line, ("\"This is a test line\"", MIME type text/plain))], :struct, "Section", "e05e54076988abf4"]

#noop
@test line(section) == "This is a test line"
------
Output
------

Page Type

Page–> The type that represents a page in a document.

  • Fields:

    • sections–> Array of Section type.
    • name–> Name of the module being documented.

source

Page–> Helper function to create constructer for Page type.

source

sections–> Getter for accessing the underlying field sections of Page.

source

name–> Getter for accessing the underlying field name of Page.

source

A 📃 is made up of several sections. These sections can be example codes, text ,graphs(to be implemented) and function documentation and several pages. The Page type helps in implementing this concept into code.

Example

begin
page=Page([Section("iny, meeny, miny mo"), Section("🙈 🙊 🙉")], "Monkey module")
sections(page)
end
------
Output
------
Any["Main.workspace#9.Section", Tuple{Int64, Any}[(1, (Dict{Symbol, Any}(:prefix => "Section", :elements => Any[(:line, ("\"iny, meeny, miny mo\"", MIME type text/plain))], :type => :struct, :prefix_short => "Section", :objectid => "c89c9716340cc7ce"), MIME type application/vnd.pluto.tree+object)), (2, (Dict{Symbol, Any}(:prefix => "Section", :elements => Any[(:line, ("\"🙈 🙊 🙉\"", MIME type text/plain))], :type => :struct, :prefix_short => "Section", :objectid => "d497a952cc02ed67"), MIME type application/vnd.pluto.tree+object))], :Array, "", "79a209370de06e21"]

page
------
Output
------
Any["Page", Any[(:sections, (Dict{Symbol, Any}(:prefix => "Main.workspace#9.Section", :elements => Tuple{Int64, Any}[(1, (Dict{Symbol, Any}(:prefix => "Section", :elements => Any[(:line, ("\"iny, meeny, miny mo\"", MIME type text/plain))], :type => :struct, :prefix_short => "Section", :objectid => "c89c9716340cc7ce"), MIME type application/vnd.pluto.tree+object)), (2, (Dict{Symbol, Any}(:prefix => "Section", :elements => Any[(:line, ("\"🙈 🙊 🙉\"", MIME type text/plain))], :type => :struct, :prefix_short => "Section", :objectid => "d497a952cc02ed67"), MIME type application/vnd.pluto.tree+object))], :type => :Array, :prefix_short => "", :objectid => "79a209370de06e21"), MIME type application/vnd.pluto.tree+object)), (:name, ("\"Monkey module\"", MIME type text/plain))], :struct, "Page", "a51ab6df27f0b54e"]

typeof(page)
------
Output
------
Page

runandupdate

runandupdatenb uses the load_notebook_nobackup function in Pluto.jl. There are multiple ways to achieve what this function achieves without depending on Pluto internals but for now this was the quickiest way to achieve this.

Note-Depending on Pluto internal to run and update a notebook makes it difficult to run unit test for this function from within pluto itself because a Pluto cell is treated as worker 2, 3 and so on but when you do load_notebook() then it spins up another worker. Only worker 1 can spwan further processes and not a notebook cell.

runandupdatenb(fn::AbstractString)–> Run the notebook in the supplied path and update the notebook with the output of each cell.

source

stitchcode

stitchcode(cell::Cell)–> Stitches the code in a Pluto notebook cell with the output of that code. The output is a code block.

source

stitchcode(cellop::AbstractString)–> Removes the quotes from a string and creates a code block with that string inside the newely formed code block

source

stitchcode(fdocs::Functiondocs)–> When supplied with a FunctionDocs type, stitchCode appends together the object docstrings and generates documentation for that particular object

source

Functiondocs

struct Functiondocs–> Stores the document of different objects.

  • funcdocs–> Array of strings.

source

Functiondocs(funcdocs)–> Helper for accessing the FunctionDocs constructer.

source

Example

begin
funcdocs=Functiondocs(["i", "j"])
funcdocs.funcdocs
end
------
Output
------
Any["String", Tuple{Int64, Any}[(1, ("\"i\"", MIME type text/plain)), (2, ("\"j\"", MIME type text/plain))], :Array, "", "c8e03403b6fd65b5"]

collectfuncdocs

collectfuncdocs(obj)–> Collects objects (functions, methods, macro structs etc.) and creates an array of documents (generated from the docstrings). Creates aFunctionDocs type from these documents.

source

Example

collectfuncdocs(stitchcode).funcdocs
------
Output
------
Any["String", Tuple{Int64, Any}[(1, ("\"> stitchcode(cell::Cell)–> Stitches the code in a Pluto notebook cell with the output of that code. The output is a code block.\\n\\n [source](https://github-link.vercel.app/api?ghUrl=https://github.com/sapal6/Nbdev.jl/blob/master/src/Documenter.jl&q=stitchcode)\"", MIME type text/plain)), (2, ("\"> stitchcode(cellop::AbstractString)–> Removes the quotes from a string and creates a code block with that string inside the newely formed code block\\n\\n [source](https://github-link.vercel.app/api?ghUrl=https://github.com/sapal6/Nbdev.jl/blob/master/src/Documenter.jl&q=stitchcode)\"", MIME type text/plain)), (3, ("\"> stitchcode(fdocs::Functiondocs)–> When supplied with a FunctionDocs type, stitchCode appends together the object docstrings and generates documentation for that particular object\\n\\n [source](https://github-link.vercel.app/api?ghUrl=https://github.com/sapal6/Nbdev.jl/blob/master/src/Documenter.jl&q=stitchcode)\"", MIME type text/plain))], :Array, "", "a839de267daaaf97"]

Higher Level API

These higher level APIs can either be used directly or are already used internally by nbdev. One such functions which can be used directly is...

showdoc

showdoc(o)–> Takes an object and builds markdown documentation.

source

#noop
begin
"""
> An example of a struct
"""
struct Mystruct
    name
end
end
------
Output
------


mystruct=Mystruct("test")
------
Output
------
Any["Mystruct", Any[(:name, ("\"test\"", MIME type text/plain))], :struct, "Mystruct", "51ee7213ed45799a"]

typeof(mystruct)
------
Output
------
Mystruct

showdoc(Mystruct)

An example of a struct

source

Currently nbdev is unable to recognize the docstrings of inline expressions.👇

#noop
"> inlinetest--> This is a inline test expression"
inlinetest=str->replace(str, "1"=> "one")
------
Output
------

createpage

CreatePage–> Creates the Page type from the markdown and example code cells of the supplied notebook. The filename is the name of the notebook which is parsed.

source

While generating document you don't need to call this function. This is done automatically😃 for you when nbdev generates documents.

savepage

savepage(io, page::Page)–> Take the contents from a Page type and write to the io

source

savepage(page::Page, path::String)–> Given a Page type and the required path, creates the related markdwon file in the specified path. The name of the resulting markdown file is same as the nameof the notebook for which the document is generated

source

Nbdev calls the required method of save_page automatically during document generation.

export2md

export2md(fn::String, path::String)–> Generate document for a file in the given path

source

export2md(fns::AbstractVector, path::String)–> Map the export2md(file, path) to a given vector of file.

source

export2md()–> Higher level API to generate documents for all the valid notebooks

source

Export.readfilenames(joinpath(pwd()))
------
Output
------
Any["Any", Tuple{Int64, Any}[(1, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\00_nbdev.jl\"", MIME type text/plain)), (2, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\01_export.jl\"", MIME type text/plain)), (3, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\02_documenter.jl\"", MIME type text/plain)), (4, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\03_codeRunner.jl\"", MIME type text/plain)), (5, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\04_make.jl\"", MIME type text/plain)), (6, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\05_common.jl\"", MIME type text/plain)), (7, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\developerguide.jl\"", MIME type text/plain)), (8, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\index.jl\"", MIME type text/plain)), (9, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\styleguide.jl\"", MIME type text/plain)), (10, ("\"C:\\\\satya\\\\julia\\\\nbdev.jl-changes\\\\nbdev-backlinks\\\\nbs\\\\tutorial.jl\"", MIME type text/plain))], :Array, "", "cd03d9b6421d53ba"]

The export2md() is what gets summoned when document generation is invoked. Like most things in nbdev (and unlike most things in life) this too gets invoked automatically. 🥳

#### export2readme
------
Output
------

export2readme()–> create readme from the contents of Index notebook

source