You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/get-started/basic-content.qmd
+16-18Lines changed: 16 additions & 18 deletions
Original file line number
Diff line number
Diff line change
@@ -7,20 +7,20 @@ jupyter:
7
7
name: python3
8
8
---
9
9
10
-
Individual content entries (e.g. a function to be documented) can also be customized.
10
+
Individual content entries (e.g. a function to be documented) can be customized.
11
11
For example, if you are documenting a Python class, you may want to include or exclude
12
12
documentation on specific methods on that class.
13
13
14
-
Specify content options by setting `name: <content name>`, along with any additional options.
14
+
Specify content options by setting `name: <content name>` followed by any additional options.
15
15
16
-
For example, below is a piece of content, MdRenderer, specified without options.
16
+
For example, below is a single content element, `MdRenderer`, without additional options.
17
17
18
18
```yaml
19
19
contents:
20
20
- MdRenderer
21
21
```
22
22
23
-
We set it to only document its render method, by setting `name: MdRenderer` followed by the `members` option.
23
+
Instead of documenting the entire `MdRenderer` class, we can only document the `MdRenderer.render` method by setting `name: MdRenderer` followed by the `members` option:
24
24
25
25
```yaml
26
26
contents:
@@ -36,10 +36,10 @@ In the following sections, we'll discuss different options for configuring conte
36
36
37
37
Finding Python objects to document involves two pieces of configuration:
38
38
39
-
* the package name.
40
-
* a list of objects for content.
39
+
1. the package name.
40
+
2. a list of objects for content.
41
41
42
-
Note that quartodoc can look up anything---whether functions, modules, classes, attributes, or methods.
42
+
quartodoc can look up a wide variety of objects, including functions, modules, classes, attributes, and methods:
43
43
44
44
```yaml
45
45
quartodoc:
@@ -55,13 +55,13 @@ quartodoc:
55
55
- renderers # module: quartodoc.renderers
56
56
```
57
57
58
-
The functions listed in `contents` are assumed to be imported from the package.
58
+
The functions listed in `contents` are those that are available for import from the package (`quartodoc` in this instance).
59
59
60
60
## Module and class members
61
61
62
-
Documentation for modules and classes can automatically include their members (e.g. class methods and attributes; everything defined inside a module).
62
+
Documentation for classes and modules can automatically include their members (e.g. class methods and attributes or everything defined inside a module, respectively).
63
63
64
-
By default, all attributes and functions (including methods on a class) are documented by embedding them inside the module or class documentation.
64
+
By default, all attributes and functions (including methods on a class) are presented in the `embedded` style, which means their documentation is located inside their respective module's or class's documentation.
65
65
66
66
There are four styles for presenting child members:
67
67
@@ -82,7 +82,7 @@ res = extract_type(DocstringSectionAttributes, choices.docstring.parsed)[0]
82
82
print(renderer.render(res))
83
83
```
84
84
85
-
You can specify a style by setting the `children` option in the config:
85
+
You can specify a style for displaying members by setting the `children` option in the config:
86
86
87
87
```yaml
88
88
quartodoc:
@@ -102,12 +102,11 @@ quartodoc:
102
102
103
103
## Setting default options
104
104
105
-
The section above showed how you can set options like `members:` and `children:` on content.
106
-
When specifying API documentation, you may need to specify the same options across multiple pieces of content.
105
+
The section above showed how you can set options like `members:` (which is a list of the items you want to show) and `children:` (the style for presenting `members`) on content.
107
106
108
-
Use the `options:` field in a section to specify options to apply across all content in that section.
107
+
However, you may desire to set the same options across multiple pieces of content. In this case, you can set default options for a section that applies to all content in that section. You can use the `options:` field to accomplish this.
109
108
110
-
For example, the config blocks below show how to document multiple classes without their members.
109
+
For example, the config below shows how to document multiple classes _without_ any child members. On the left, you can see the config without setting the default option, and on the right, you can see the config with the default option set.
111
110
112
111
:::::: {.columns}
113
112
::: {.column}
@@ -151,12 +150,11 @@ quartodoc:
151
150
:::
152
151
::::::
153
152
154
-
Note that the **with options** block sets `members: []` inside `options`.
155
-
This sets `members: []` as the default for each piece of content.
153
+
By setting `members: []` in the options block, we are telling quartodoc to not include any members for each piece of content.
156
154
157
155
### Reusing options
158
156
159
-
Options can be given a name, and re-used in multiple sections:
157
+
Options can be given a name and re-used in multiple sections:
In order to install quarto, see the quarto [get started page](https://quarto.org/docs/get-started/).
32
+
:::{.callout-important}
33
+
34
+
### Install Quarto
35
+
36
+
If you haven't already, you'll need to [install Quarto](https://quarto.org/docs/get-started/) before you can use quartodoc.
39
37
:::
40
38
41
39
42
40
## Basic use
43
41
44
-
Getting started with quartodoc takes two steps: configuring a quarto website,
45
-
and generating documentation pages for your library.
42
+
Getting started with quartodoc takes two steps: configuring quartodoc, then generating documentation pages for your library.
46
43
47
-
First, create a `_quarto.yml` file with the following:
44
+
You can configure quartodoc alongside the rest of your Quarto site in the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html) file you are already using for Quarto. To [configure quartodoc](basic-docs.qmd#site-configuration), you need to add a `quartodoc` section to the top level your `_quarto.yml` file. Below is a minimal example of a configuration that documents the `quartodoc` package:
48
45
49
46
```yaml
50
47
project:
@@ -56,7 +53,7 @@ metadata-files:
56
53
57
54
58
55
quartodoc:
59
-
# the name used to import the package
56
+
# the name used to import the package you want to create reference docs for
60
57
package: quartodoc
61
58
62
59
# write sidebar data to this file
@@ -72,13 +69,13 @@ quartodoc:
72
69
- preview
73
70
```
74
71
75
-
Next, run this command to generate your API pages:
72
+
Now that you have configured quartodoc, you can generate the reference API docs with the following command:
76
73
77
74
```bash
78
75
quartodoc build
79
76
```
80
77
81
-
This should create a `reference/` directory with an `index.qmd` and documentation
78
+
This will create a `reference/` directory with an `index.qmd` and documentation
82
79
pages for listed functions, like `get_object` and `preview`.
83
80
84
81
Finally, preview your website with quarto:
@@ -105,12 +102,12 @@ quarto preview
105
102
106
103
## Looking up objects
107
104
108
-
Finding python objects to document involves two pieces of configuration:
105
+
Generating API reference docs for Python objects involves two pieces of configuration:
109
106
110
-
* the package name.
111
-
* a list of objects for content.
107
+
1. the package name.
108
+
2. a list of objects for content.
112
109
113
-
Note that quartodoc can look up anything---whether functions, modules, classes, attributes, or methods.
110
+
quartodoc can look up a wide variety of objects, including functions, modules, classes, attributes, and methods:
0 commit comments