Auf dieser Seite

Guidedog / Dokumentation 0.2.0

project

Package project builds a documentation project the way Sphinx does: a source directory with conf.toml, builders writing _build/<builder>, and incremental builds. It is host code and may allocate; documents are read and rendered by the Guidedoc engine.

Its surface is the verbs on a Project (project.odin says who owns what they allocate) and the types they take and return; every other file is #+private. lib/project/README.md lists the surface.

Types

project.Build_Options :: struct

Build_Options are one build’s command-line options; build copies them.

all: bool

-a: write every output, not only outdated ones.

fresh: bool

-E: ignore the saved environment.

nitpicky: bool

-n

warnings_as_errors: bool

-W

keep_going: bool

--keep-going

untrusted: bool

--untrusted: see untrusted_policy.

jobs: int

-j: reading threads; 0 or 1 is one, -1 one per core.

budget: int

--budget: bytes; 0 is BUILD_BUDGET.

memory: host.Budget_Policy

when the budget is reached: –memory, or ask.

heap: mem.Allocator

Where steps‘ scratch memory comes from (a document read, a page rendered); zero: the heap. Reading threads use it at once, so it must be thread-safe.

max_depth: int

--max-depth: how deep content may nest; 0 is the default.

max_nodes: int

--max-nodes: nodes per document; 0 is the default.

stack_bytes: int

--stack-kib: stack budget; 0 is the default. See build_limits.

tags: []string

-t

output_dir: string

sphinx-build form; otherwise build_dir/<builder>.

arena_block: int

bytes the build’s arenas ask for at a time; 0 is 64 KiB.

now: datetime.DateTime

the build’s moment; zero is now, in UTC.

year: string

project.Build_Result :: struct

Build_Result is what a build did: exit 0, or exit != 0 with a problem; the reports of the whole build either way, and its counters. It owns everything it refers to, in its arena, until release.

exit: int

problem: host.Problem

reports: []host.Report

read: int

documents parsed.

unread: int

documents that could not be read.

reused: int

documents taken from the environment.

written: int

outputs written: published, or only prepared when not published.

unchanged: int

outputs already up to date.

output: string

reached: Build_Stage

how far the build got.

published: bool

the outputs are in place; otherwise the previous ones stay,

unsettled: bool

unless this is set: a publication neither finished nor undone.

peak: int

the most memory the budget held at once, in bytes.

budget: int

the budget at the end, in bytes: Budget_Policy may raise it.

memory: ^Memory

everything the build allocated; see release.

owner: mem.Allocator

the allocator memory came from.

project.Build_Stage :: enum

Build_Stage is how far a build got, so its summary says what it did and no more.

Preparing

settings, the documents to read, the readers: no document read yet.

Reading

reading the documents and resolving their references.

Writing

writing the outputs beside the output folder.

Written

every output written; publishing them is what is left.

project.Builder_Kind :: enum u8

Builder_Kind is the output a build writes; BUILDER_NAMES are the names the command line gives them, and builder_named reads a name.

Html

Dirhtml

Singlehtml

Pdf

Text

Gettext

Dummy

project.Config :: struct

Config holds conf.toml. Names follow conf.py so a Sphinx user recognizes them.

source_dir: string

the directory holding conf.toml (absolute).

build_dir: string

_build beside it, or build/ in the separated layout.

project: string

Project.

author: string

Project.

copyright: string

Project.

version: string

Project.

release: string

Project.

today: string

Project.

today_fmt: string

Project.

language: string

root_doc: string

General.

source_suffix: []string

exclude_patterns: []string

include_roots: []string

folders beyond the source folder files may come from.

include_patterns: []string

templates_path: []string

extensions: []string

rst_prolog: string

rst_epilog: string

default_role: string

primary_domain: string

highlight_language: string

pygments_style: string

Pygments style for code; „“ is the theme’s.

pygments_dark_style: string

for dark pages; „“ is github-dark.

numfig: bool

numfig_format: map[string]string

numfig_secnum_depth: int

math_number_all: bool

math_eqref_format: string

math_numfig: bool

nitpicky: bool

nitpick_ignore: [][2]string

nitpick_ignore_regex: [][2]string

nitpick_patterns: [][2]regex.Regular_Expression

nitpick_ignore_regex, compiled.

show_authors: bool

add_function_parentheses: bool

add_module_names: bool

toc_object_entries: bool

toc_object_entries_show_parents: string

„domain“, „hide“, or „all“.

trim_footnote_reference_space: bool

smartquotes: bool

keep_warnings: bool

suppress_warnings: []string

todo_include_todos: bool

autosectionlabel_prefix_document: bool

labels are „docname:Title“.

autosectionlabel_maxdepth: int

sections this deep or deeper get no label; 0: all.

trim_doctest_flags: bool

doctest flags and <BLANKLINE> hidden in sessions.

manpages_url: string

option_emphasise_placeholders: bool

extlinks: map[string][2]string

extlinks_detect_hardcoded_links: bool

object_types: [dynamic]sphinx.Object_Type

see object_types.odin.

directive_aliases: []sphinx.Directive_Alias

mathjax_path: string

sphinx.ext.mathjax, Sphinx’s HTML math; see mathjax.odin.

mathjax_options: map[string]string

mathjax_inline: []string

each an opening and a closing delimiter.

mathjax_display: []string

each an opening and a closing delimiter.

mathjax3_config: string

JSON, as json.dumps writes the table.

mathjax4_config: string

JSON, as json.dumps writes the table.

mathjax_config_path: string

intersphinx_mapping: []Intersphinx_Project

sphinx.ext.intersphinx; see intersphinx.odin.

intersphinx_cache_limit: int

days an inventory is reused; below 0: always.

intersphinx_timeout: int

seconds; 0: no limit, as None in conf.py.

intersphinx_disabled_reftypes: []string

intersphinx_resolve_self: string

autodoc_source_paths: []string

sphinx.ext.autodoc, which reads Python source without running it; see autodoc.odin.

folders holding the packages, like sys.path.

autoclass_content: string

autodoc_class_signature: string

autodoc_default_options: []ad.Default_Option

autodoc_docstring_signature: bool

autodoc_inherit_docstrings: bool

autodoc_member_order: string

autodoc_mock_imports: []string

accepted: nothing is imported, so nothing is mocked.

autodoc_preserve_defaults: bool

autodoc_typehints: string

autodoc_typehints_description_target: string

autodoc_typehints_format: string

autodoc_type_aliases: map[string]string

autodoc_use_type_comments: bool

autodoc_warningiserror: bool

python_display_short_literal_types: bool

strip_signature_backslash: bool

odin_autoapi_dirs: []string

The odin domain’s generating directives and API pages; see odin.odin.

folders whose packages get API pages.

odin_collections: map[string]string

collection name to folder („core“).

odin_autoapi_root: string

the folder of the generated pages: „api“.

odin_autoapi_options: []string

members, undoc-members, private-members.

odin_autoapi_member_order: string

source, alphabetical, groupwise.

odin_autoapi_add_toctree_entry: bool

the API index joins the root’s toctree.

odin_autoapi_generate_api_docs: bool

false: only the directives read the dirs.

html_theme: string

HTML.

html_theme_options: map[string]string

html_title: string

html_short_title: string

html_logo: string

html_favicon: string

html_static_path: []string

html_extra_path: []string

html_css_files: []string

html_js_files: []string

html_last_updated_fmt: Maybe(string)

unset: no date; „“: the default format.

html_permalinks: bool

html_permalinks_icon: string

html_use_index: bool

html_domain_indices: bool

the Python module index, py-modindex.html.

modindex_common_prefix: []string

prefixes the module index leaves out.

html_split_index: bool

html_copy_source: bool

html_show_sourcelink: bool

html_sourcelink_suffix: string

html_show_copyright: bool

html_show_sphinx: bool

html_baseurl: string

html_file_suffix: string

html_link_suffix: string

html_secnumber_suffix: string

html_context: Toml_Value

a table, as written: the pages‘ variables.

html_additional_pages: map[string]string

page name: the template it is made from.

pdf_documents: []Pdf_Document

PDF.

pdf_paper_size: string

pdf_logo: string

pdf_toplevel_sectioning: string

pdf_show_urls: string

pdf_preamble: string

pdf_packages: string

pdf_fonts: string

pdf_font_paths: []string

typst: string

graphviz_output_format: string

Graphviz, linked in through graphdog.

svg; png is read as svg.

graphviz_dot_args: []string

-Gname=value, -Nname=value, -Ename=value.

graphviz_dot: string

accepted from conf.py; Graphviz is built in.

myst_enable_extensions: []string

Markdown, with myst-parser 0.16.1’s names; the reader has the support built in.

optional syntax, such as colon_fence.

myst_heading_anchors: int

heading depth that gets slug anchors; 0: none.

myst_dmath_allow_labels: bool

myst_dmath_allow_space: bool

myst_dmath_allow_digits: bool

myst_dmath_double_inline: bool

myst_linkify_fuzzy_links: bool

myst_substitutions: map[string]string

myst_sub_delimiters: []string

two characters, each doubled: {{ name }}.

myst_url_schemes: []string

schemes that make external links; empty: all.

myst_footnote_transition: bool

myst_html_meta: map[string]string

myst_commonmark_only: bool

CommonMark syntax only; headings still make sections.

myst_disable_syntax: []string

markdown-it rule names not parsed.

myst_words_per_minute: int

myst_dmath_enable: bool

deprecated spellings of the extensions.

myst_amsmath_enable: bool

deprecated spellings of the extensions.

locale_dirs: []string

Internationalization, with Sphinx’s names (see lib/i18n).

relative to the source directory.

gettext_compact: Flag_Or_Name

true, false, or one catalog’s name.

gettext_uuid: bool

gettext_location: bool

gettext_auto_build: bool

compile .po files to .mo beside them.

gettext_additional_targets: []string

gettext_exclude_patterns: []string

document paths excluded from extraction only.

gettext_allow_fuzzy_translations: bool

gettext_last_translator: string

gettext_language_team: string

figure_language_filename: string

translation_progress_classes: Flag_Or_Name

true, false, translated, untranslated.

html_title_derived: bool

html_title was made from the project name.

html_short_title_derived: bool

project.Flag_Or_Name :: struct

Flag_Or_Name is a setting that is true, false, or a name, as gettext_compact is.

on: bool

name: string

the name, when one was given; on is then true.

project.Intersphinx_Project :: struct

Intersphinx_Project is one intersphinx_mapping entry: the name references use as a prefix, the base URL of the other project’s pages, and where its inventory is, tried in order; „“ stands for None, the base URL’s objects.inv.

name: string

uri: string

locations: []string

project.Intl_Action :: enum u8

Intl_Action is what intl_update did to one catalog.

Create

Update

Not_Changed

project.Intl_File :: struct

Intl_File is one catalog intl_update or intl_stat looked at, with its statistics.

action: Intl_Action

path: string

stats: gettext.Stats

project.Intl_Options :: struct

Intl_Options are sphinx-intl’s options for update and stat.

pot_dir: string

-p: the templates; default: the gettext builder’s output.

locale_dir: string

-d: default: the first of locale_dirs.

languages: []string

-l, repeatable; default: the project’s language.

width: int

-w: line width; 0 means 76.

obsolete: bool

keep obsolete messages (sphinx-intl’s default).

project.Load_Options :: struct

Load_Options are the command line’s say in where a project is and how it is set; load borrows them for the call.

conf_dir: string

-c: where conf.toml is, when not in the source directory.

no_config: bool

-C: build with defaults only.

overrides: []string

-D name=value, applied after conf.toml.

source: string

sphinx-build form: explicit source directory.

output: string

sphinx-build form: explicit output directory.

project.Migrate_Options :: struct

input: string

conf.py, guidedog.toml, or a folder holding one.

output: string

where conf.toml goes; „“ is beside the input, „-„ writes nothing.

force: bool

replace an existing conf.toml.

year: string

what datetime’s current year evaluates to.

project.Migrate_Result :: struct

Migrate_Result is what migrate wrote (toml, and output unless that was „-„), with notes on what it could not convert as written, and how many settings it converted.

input: string

output: string

toml: string

notes: []host.Report

converted: int

settings written to conf.toml.

attention: int

settings left out that may matter.

project.Pdf_Document :: struct

Pdf_Document is one book of pdf_documents: which document it starts from, and the file, title, and author it gets.

root: string

the root document of the book.

file: string

the PDF name in _build/pdf.

title: string

author: string

project.Project :: struct

Project is a loaded documentation project. The API is a handful of verbs over it:

p, problem := project.load("docs", {}, defaults.registry())
defer project.unload(&p)
if problem.exit != 0 do return problem.exit
result := project.build(&p, .Html, {})
defer project.release(&result)
project.clean(&p)

Who owns what each entry point allocates, all of it taken from context.allocator:

• load: the project owns everything, in an arena of its own; unload releases it, including the text of a problem load returned, so it is called whether load succeeded or not.
• build: the result owns everything the build allocated, in an arena of its own; release frees it. The project is never changed by a build (see build), so it may be built any number of times, and must outlive every result of its builds only while their reports are used. load, build, release, unload leaves nothing live.
• serve: each request works in an arena it frees; the rebuild callback owns (and releases) the results of the builds it runs.
• clean, intl_update, intl_stat, migrate, quickstart: their results and problems are allocated in context.allocator and not freed one by one; a caller on the heap runs them with an arena (or the temporary allocator) as context.allocator and frees it once it has used them.
• builder_named, absolute, join: plain values; absolute and join allocate the path.

config: Config

warnings: [dynamic]host.Report

from configuration; builds add their own.

registry: gd.Registry

settings: string

digest of conf.toml and the -D overrides: what every output uses.

memory: ^Memory

everything load allocated; see unload.

owner: mem.Allocator

the allocator memory came from.

project.Quickstart_Options :: struct

Quickstart_Options are guidedog quickstart’s answers; „“ takes each default.

dir: string

project: string

author: string

version: string

release: string

language: string

suffix: string

„.rst“ by default.

root_doc: string

„index“ by default.

separate: bool

source/ and build/ instead of one folder with _build.

year: string

for the copyright line.

date: string

for the root document’s comment.

project.Server :: struct

Server previews the built html output on the loopback interface. Before serving a page it checks whether any source changed and rebuilds incrementally if so.

project: ^Project

rebuild: proc(s: ^Server) -> bool

returns false when the rebuild failed.

user: rawptr

stamp: i64

fingerprint of watched paths, sizes, and modification times.

project.Toml_Kind :: enum u8

TOML 1.0: tables, arrays of tables, dotted and quoted keys, inline tables, arrays, every string form, integers in all bases, floats, booleans, and date-times (kept as text). Errors carry the line, so a mistake in conf.toml points at itself.

String

Integer

Float

Boolean

Datetime

Array

Table

project.Toml_Value :: struct

Toml_Value is one parsed TOML value; Config.html_context keeps a table of them as written. Its strings and lists belong to the project that loaded it.

kind: Toml_Kind

text: string

String and Datetime.

integer: i64

float: f64

boolean: bool

items: [dynamic]Toml_Value

Array.

keys: [dynamic]string

Table, in definition order.

values: [dynamic]Toml_Value

Table, parallel to keys.

line: int

defined: bool

Table: defined by a header or as a value, not only implied.

inline: bool

written inline, so it may not be extended later.

Procedures

project.absolute :: proc(path: string) -> string

absolute makes a path absolute against the working directory without resolving it, so it works for folders a build has not created yet. The path is allocated in the context allocator and owned by the caller.

project.build :: proc(p: ^Project, kind: Builder_Kind, o: Build_Options) -> Build_Result

build reads, resolves, and writes the project with one builder. Outputs are written only for documents whose inputs changed, unless o.all is set.

Ownership: the build allocates everything, its result included, in an arena of its own taken from context.allocator, and release frees it: a caller releases each result once it is done with its reports. The build never changes the project: it works on its own copy of the configuration (build_config), so an –untrusted build confines only itself, and any number of builds may follow on the same project.

The memory of each step (a document read, a page rendered) comes from o.heap, the heap by default, and is freed when the step ends. When context.allocator or o.heap refuses memory, the build stops with host.memory (exit 3) and publishes nothing.

project.build_limits :: proc(o: Build_Options) -> (gd.Limits, host.Problem)

build_limits are the limits every session of a build reads and renders with: the documented defaults, with –max-depth, –max-nodes, and –stack-kib. Reading runs on the main thread, or on core:thread’s threads with -j, and pages render on the main thread, so the stack budget may be at most what the smaller of those stacks holds (host.stack_budget_limit); without –stack-kib it is the default, or less on a thread too small for it. A –stack-kib above that is the problem build.stack (exit 2); a caller may call it before build to refuse the options early. Only the problem’s message is allocated.

project.builder_named :: proc(name: string) -> (Builder_Kind, bool)

builder_named accepts Guidedog’s builder names and the Sphinx names that map onto them: the LaTeX builders become pdf, because Guidedog typesets PDF with Typst.

project.clean :: proc(p: ^Project) -> host.Problem

clean removes everything in the project’s build directory, as make clean does for Sphinx, and leaves the directory itself; a missing one is nothing to clean. It stops at the first file it cannot remove and returns its problem (host.io), whose text is allocated in the caller’s context allocator and owned by the caller.

project.intl_stat :: proc(p: ^Project, options: Intl_Options) -> ([]Intl_File, host.Problem)

intl_stat is sphinx-intl stat: the translated, fuzzy, and untranslated messages of every catalog of the languages. It writes nothing; the files are allocated in context.allocator (see Project).

project.intl_update :: proc(p: ^Project, options: Intl_Options) -> ([]Intl_File, host.Problem)

intl_update is sphinx-intl update: for each template of pot_dir and each language, it creates the translation catalog, or merges the template into the existing one (gettext.merge: kept, fuzzy, and obsolete messages, as msgmerge does). It returns what it did to each catalog, allocated in context.allocator (see Project), or the first problem, with the catalogs written before it kept.

project.join :: proc(parts: ..string) -> string

join joins path parts with the system’s separator and cleans the result, as filepath.join does; the path is allocated in context.allocator.

project.load :: proc(dir: string, options: Load_Options, registry: gd.Registry) -> (p: Project, problem: host.Problem)

load finds the project from dir (see find_project) or the explicit directories in options, and reads its configuration. The registry is checked first: an adapter with no ID, version, or procedure, or an ID registered twice, is a problem, as it is for gd.convert. Whether it has the readers the documents need is known once a build has found them (find_readers). The project owns everything load allocates, in an arena taken from context.allocator, which unload frees; a problem’s text lives in that arena too. When that allocator refuses memory, load stops with host.memory (exit 3), and unload is still what frees the rest.

project.migrate :: proc(o: Migrate_Options) -> (r: Migrate_Result, problem: host.Problem)

migrate turns the Sphinx conf.py (or a guidedog.toml) that o.input names into conf.toml, and writes it unless o.output is „-„: literal assignments become settings, and what Python would have computed is reported in r.notes. The written conf.toml is loaded first, so it always builds; an existing one is refused unless o.force is set. Everything is allocated in context.allocator (see Project); a failure is the problem, with nothing written.

project.quickstart :: proc(o: Quickstart_Options) -> (created: []string, p: host.Problem)

quickstart creates a documentation project in o.dir laid out as Sphinx lays one out, with conf.toml, a root document, and the default templates copied in so they can be edited, and returns the paths it created. It refuses to overwrite a project. The paths and the problem are allocated in context.allocator (see Project).

project.release :: proc(r: ^Build_Result)

release frees everything a build allocated, its result included, which is empty after.

project.serve :: proc(s: ^Server, port: int) -> host.Problem

serve previews the project’s built html output on 127.0.0.1:port, rebuilding through s.rebuild before a page is served when a source changed since the last build. It borrows s and the project for as long as it runs, which is until the process ends: it returns only the problem of a port it cannot listen on. Each request works in an arena of its own on the heap, freed when it is answered.

project.unload :: proc(p: ^Project)

unload releases everything load allocated.

Constants

project.BUILD_BUDGET :: 1 << 30

BUILD_BUDGET bounds what the build holds at once: its sessions, and the files it reads: reading threads wait rather than exceed it (see host.Budget). –budget sets another.

project.CONFIG_FILE :: "conf.toml"

CONFIG_FILE is the name of a project’s configuration, in its source directory.

Variables

@(rodata) project.BUILDER_NAMES