|
| 1 | +--- |
| 2 | +title: Building layouts |
| 3 | +jupyter: |
| 4 | + jupytext: |
| 5 | + text_representation: |
| 6 | + extension: .qmd |
| 7 | + format_name: quarto |
| 8 | + format_version: '1.0' |
| 9 | + jupytext_version: 1.14.5 |
| 10 | + kernelspec: |
| 11 | + display_name: Python 3 (ipykernel) |
| 12 | + language: python |
| 13 | + name: python3 |
| 14 | +--- |
| 15 | + |
| 16 | +quartodoc has 4 main pieces: |
| 17 | + |
| 18 | +* Builder: the class responsible for reading a `_quarto.yml`, and generating docs. |
| 19 | +* Layout: a specification of the docs, that the builder enhances to fully specify "what should get rendered and how?". |
| 20 | +* Docstring objects: a representation of parsed docstrings, and the python objects they belong to. |
| 21 | +* Renderer: the class responsible for rendering layouts and doc objects. |
| 22 | + |
| 23 | +```{python} |
| 24 | +from quartodoc import Builder, layout, get_object, MdRenderer, preview |
| 25 | +``` |
| 26 | + |
| 27 | +## Builder |
| 28 | + |
| 29 | +```{python} |
| 30 | +config = {"quartodoc": |
| 31 | + { |
| 32 | + "package": "quartodoc", |
| 33 | + "style": "pkgdown", |
| 34 | + "sections": [ |
| 35 | + { |
| 36 | + "title": "some section", |
| 37 | + "desc": "some description", |
| 38 | + "contents": [ |
| 39 | + "get_object", |
| 40 | + "MdRenderer" |
| 41 | + ] |
| 42 | + } |
| 43 | + ] |
| 44 | + } |
| 45 | +} |
| 46 | +builder = Builder.from_quarto_config(config) |
| 47 | +``` |
| 48 | + |
| 49 | +```{python} |
| 50 | +preview(builder.layout) |
| 51 | +``` |
| 52 | + |
| 53 | +```{python} |
| 54 | +blueprint = builder.do_blueprint() |
| 55 | +preview(blueprint, max_depth=6) |
| 56 | +``` |
| 57 | + |
| 58 | +## Layout |
| 59 | + |
| 60 | +The layout classes represent documentation to build. |
| 61 | + |
| 62 | +See the [layouts API reference](reference/layout.qmd). |
| 63 | + |
| 64 | +* Section: a section of documentation, with a title and description. |
| 65 | +* Page: represents a page of documentation. |
| 66 | +* Doc: represents a python object and its docstring to render. |
| 67 | +* DocClass, DocModule: has a members field. |
| 68 | +* Auto: an object (e.g. function) to look up, and turn into the appropriate Doc class. |
| 69 | + This is the default class used in the config, and has options for customizing |
| 70 | + documentation, such as how to document members of a class. |
| 71 | + |
| 72 | +Note that classes like Doc include docstring objects, that are the result of |
| 73 | +statically analyzing the target library with griffe. |
| 74 | + |
| 75 | +```{python} |
| 76 | +doc_page = blueprint.sections[0].contents[0] |
| 77 | +preview(doc_page, max_depth = 4) |
| 78 | +``` |
| 79 | + |
| 80 | +## Docstring objects |
| 81 | + |
| 82 | +```{python} |
| 83 | +obj = get_object("quartodoc", "get_object") |
| 84 | +``` |
| 85 | + |
| 86 | +## Renderer |
| 87 | + |
| 88 | +The renderer is responsible for converting layout and docstring objects into a |
| 89 | +string of documentation (e.g. markdown). |
| 90 | + |
| 91 | +```{python} |
| 92 | +renderer = MdRenderer() |
| 93 | +
|
| 94 | +print( |
| 95 | + renderer.render(obj)[:150] |
| 96 | +) |
| 97 | +``` |
| 98 | + |
| 99 | +Note that it is also capable of rendering most layout objects, such as a Page. |
| 100 | + |
| 101 | +```{python} |
| 102 | +doc_page = blueprint.sections[0].contents[0] |
| 103 | +
|
| 104 | +# not run, since it produces a lot of output! |
| 105 | +# renderer.render(doc_page) |
| 106 | +``` |
0 commit comments