Skip to content

Commit ddd25d5

Browse files
gadenbuiegadenbuie
committed
Merged upstream/main into feat/sidebar-options
2 parents e8a624f + 8d7ade2 commit ddd25d5

File tree

9 files changed

+125
-56
lines changed

9 files changed

+125
-56
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ jobs:
5656
- uses: actions/checkout@v2
5757
- uses: actions/setup-python@v2
5858
with:
59-
python-version: "${{ matrix.python-version }}"
59+
python-version: "3.10"
6060
- name: Install dev dependencies
6161
run: |
6262
python -m pip install --upgrade pip

‎quartodoc/builder/blueprint.py‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -371,12 +371,6 @@ def _fetch_members(self, el: Auto, obj: dc.Object | dc.Alias):
371371
if obj.is_module and obj.exports is not None:
372372
options = {k: v for k, v in options.items() if v.is_exported}
373373

374-
if el.include:
375-
raise NotImplementedError("include argument currently unsupported.")
376-
377-
if el.exclude:
378-
raise NotImplementedError("exclude argument currently unsupported.")
379-
380374
if not el.include_private:
381375
options = {k: v for k, v in options.items() if not k.startswith("_")}
382376

@@ -407,7 +401,18 @@ def _fetch_members(self, el: Auto, obj: dc.Object | dc.Alias):
407401
if not el.include_functions:
408402
options = {k: v for k, v in options.items() if not v.is_function}
409403

410-
return sorted(options)
404+
if el.include:
405+
raise NotImplementedError("include argument currently unsupported.")
406+
407+
if el.exclude:
408+
options = {k: v for k, v in options.items() if k not in el.exclude}
409+
410+
if el.member_order == "alphabetical":
411+
return sorted(options)
412+
elif el.member_order == "source":
413+
return list(options)
414+
else:
415+
raise ValueError(f"Unsupported value of member_order: {el.member_order}")
411416

412417

413418
class _PagePackageStripper(PydanticTransformer):

‎quartodoc/layout.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -221,10 +221,11 @@ class AutoOptions(_Base):
221221

222222
# other options ----
223223
include: Optional[str] = None
224-
exclude: Optional[str] = None
224+
exclude: Optional[list[str]] = None
225225
dynamic: Union[None, bool, str] = None
226226
children: ChoicesChildren = ChoicesChildren.embedded
227227
package: Union[str, None, MISSING] = MISSING()
228+
member_order: Literal["alphabetical", "source"] = "alphabetical"
228229
member_options: Optional["AutoOptions"] = None
229230

230231
# for tracking fields users manually specify
@@ -249,6 +250,7 @@ class Auto(AutoOptions):
249250
path the object, and short is the name of the object (i.e. no periods).
250251
members:
251252
A list of members, such as attributes or methods on a class, to document.
253+
If members is specified, no other includes or excludes are applied.
252254
include_private:
253255
Whether to include members starting with "_"
254256
include_imports:
@@ -266,7 +268,8 @@ class Auto(AutoOptions):
266268
include:
267269
(Not implemented). A list of members to include.
268270
exclude:
269-
(Not implemented). A list of members to exclude.
271+
A list of members to exclude. This is performed last, in order to subtract
272+
from the results of options like include_functions.
270273
dynamic:
271274
Whether to dynamically load docstring. By default docstrings are loaded
272275
using static analysis. dynamic may be a string pointing to another object,
@@ -275,6 +278,9 @@ class Auto(AutoOptions):
275278
Style for presenting members. Either separate, embedded, or flat.
276279
package:
277280
If specified, object lookup will be relative to this path.
281+
member_order:
282+
Order to present members in, either "alphabetical" or "source" order.
283+
Defaults to alphabetical sorting.
278284
member_options:
279285
Options to apply to members. These can include any of the options above.
280286

‎quartodoc/renderers/base.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,15 @@ def escape(val: str):
1313
return f"`{val}`"
1414

1515

16-
def sanitize(val: str, allow_markdown=False):
16+
def sanitize(val: str, allow_markdown=False, escape_quotes=False):
1717
# sanitize common tokens that break tables
1818
res = val.replace("\n", " ").replace("|", "\\|")
1919

2020
# sanitize elements that get turned into smart quotes
21-
res = res.replace("'", r"\'").replace('"', r"\"")
21+
# this is to avoid defaults that are strings having their
22+
# quotes screwed up.
23+
if escape_quotes:
24+
res = res.replace("'", r"\'").replace('"', r"\"")
2225

2326
# sanitize elements that can get interpreted as markdown links
2427
# or citations

‎quartodoc/renderers/md_renderer.py‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,8 @@ class ParamRow:
5959
def to_definition_list(self):
6060
name = self.name
6161
anno = self.annotation
62-
desc = self.description
63-
default = sanitize(str(self.default))
62+
desc = sanitize(self.description, allow_markdown=True)
63+
default = sanitize(str(self.default), escape_quotes=True)
6464

6565
part_name = (
6666
Span(Strong(name), Attr(classes=["parameter-name"]))
@@ -77,7 +77,7 @@ def to_definition_list(self):
7777
# in the table display format, not description lists....
7878
# by this stage _required_ is basically a special token to indicate
7979
# a required argument.
80-
if default is not None:
80+
if self.default is not None:
8181
part_default_sep = Span(" = ", Attr(classes=["parameter-default-sep"]))
8282
part_default = Span(default, Attr(classes=["parameter-default"]))
8383
else:
@@ -100,13 +100,15 @@ def to_definition_list(self):
100100

101101
def to_tuple(self, style: Literal["parameters", "attributes", "returns"]):
102102
name = self.name
103+
description = sanitize(self.description, allow_markdown=True)
104+
103105
if style == "parameters":
104106
default = "_required_" if self.default is None else escape(self.default)
105-
return (name, self.annotation, self.description, default)
107+
return (name, self.annotation, description, default)
106108
elif style == "attributes":
107-
return (name, self.annotation, self.description)
109+
return (name, self.annotation, description)
108110
elif style == "returns":
109-
return (name, self.annotation, self.description)
111+
return (name, self.annotation, description)
110112

111113
raise NotImplementedError(f"Unsupported table style: {style}")
112114

@@ -217,7 +219,7 @@ def render_annotation(self, el: str) -> str:
217219
el:
218220
An object representing a type annotation.
219221
"""
220-
return sanitize(el)
222+
return sanitize(el, escape_quotes=True)
221223

222224
@dispatch
223225
def render_annotation(self, el: None) -> str:
@@ -563,6 +565,9 @@ def render(self, el: dc.Parameter):
563565
res = f"{glob}{name}: {annotation} = {el.default}"
564566
elif annotation:
565567
res = f"{glob}{name}: {annotation}"
568+
else:
569+
res = f"{glob}{name}"
570+
566571
elif has_default:
567572
res = f"{glob}{name}={el.default}"
568573
else:
@@ -595,8 +600,9 @@ def render(self, el: ds.DocstringSectionParameters):
595600
@dispatch
596601
def render(self, el: ds.DocstringParameter) -> ParamRow:
597602
annotation = self.render_annotation(el.annotation)
598-
clean_desc = sanitize(el.description, allow_markdown=True)
599-
return ParamRow(el.name, clean_desc, annotation=annotation, default=el.default)
603+
return ParamRow(
604+
el.name, el.description, annotation=annotation, default=el.default
605+
)
600606

601607
# attributes ----
602608

@@ -611,7 +617,7 @@ def render(self, el: ds.DocstringSectionAttributes):
611617
def render(self, el: ds.DocstringAttribute) -> ParamRow:
612618
return ParamRow(
613619
el.name,
614-
sanitize(el.description or "", allow_markdown=True),
620+
el.description or "",
615621
annotation=self.render_annotation(el.annotation),
616622
)
617623

@@ -680,7 +686,7 @@ def render(self, el: ds.DocstringReturn):
680686
# similar to DocstringParameter, but no name or default
681687
return ParamRow(
682688
el.name,
683-
sanitize(el.description, allow_markdown=True),
689+
el.description,
684690
annotation=self.render_annotation(el.annotation),
685691
)
686692

@@ -689,7 +695,7 @@ def render(self, el: ds.DocstringRaise) -> ParamRow:
689695
# similar to DocstringParameter, but no name or default
690696
return ParamRow(
691697
None,
692-
sanitize(el.description, allow_markdown=True),
698+
el.description,
693699
annotation=self.render_annotation(el.annotation),
694700
)
695701

‎quartodoc/tests/__snapshots__/test_renderers.ambr‎

Lines changed: 34 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,17 @@
77
tests.example_signature.a_complex_signature(
88
x: list[C | int | None]
99
y: pathlib.Pathlib
10+
z
1011
)
1112
```
1213

1314
## Parameters {.doc-section .doc-section-parameters}
1415

15-
| Name | Type | Description | Default |
16-
|--------|--------------------------------------------------------------------------------------|-----------------|------------|
17-
| x | [list](`list`)\[[C](`quartodoc.tests.example_signature.C`) \| [int](`int`) \| None\] | The x parameter | _required_ |
18-
| y | [pathlib](`pathlib`).[Pathlib](`pathlib.Pathlib`) | The y parameter | _required_ |
16+
| Name | Type | Description | Default |
17+
|--------|--------------------------------------------------------------------------------------|-------------------------------|------------|
18+
| x | [list](`list`)\[[C](`quartodoc.tests.example_signature.C`) \| [int](`int`) \| None\] | The x parameter | _required_ |
19+
| y | [pathlib](`pathlib`).[Pathlib](`pathlib.Pathlib`) | The y parameter | _required_ |
20+
| z | | The z parameter (unannotated) | _required_ |
1921
'''
2022
# ---
2123
# name: test_render_annotations_complex_no_interlinks
@@ -26,15 +28,17 @@
2628
tests.example_signature.a_complex_signature(
2729
x: list[C | int | None]
2830
y: pathlib.Pathlib
31+
z
2932
)
3033
```
3134

3235
## Parameters {.doc-section .doc-section-parameters}
3336

34-
| Name | Type | Description | Default |
35-
|--------|--------------------------|-----------------|------------|
36-
| x | list\[C \| int \| None\] | The x parameter | _required_ |
37-
| y | pathlib.Pathlib | The y parameter | _required_ |
37+
| Name | Type | Description | Default |
38+
|--------|--------------------------|-------------------------------|------------|
39+
| x | list\[C \| int \| None\] | The x parameter | _required_ |
40+
| y | pathlib.Pathlib | The y parameter | _required_ |
41+
| z | | The z parameter (unannotated) | _required_ |
3842
'''
3943
# ---
4044
# name: test_render_doc_class[embedded]
@@ -483,77 +487,77 @@
483487
List
484488
# Parameters {.doc-section .doc-section-parameters}
485489

486-
<code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
490+
<code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation}</code>
487491

488492
: A description.
489493

490494
# Returns {.doc-section .doc-section-returns}
491495

492-
<code>[]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
496+
<code>[]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation}</code>
493497

494498
: A description.
495499

496500
# Attributes {.doc-section .doc-section-attributes}
497501

498-
<code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
502+
<code>[**int**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation}</code>
499503

500504
: A description.
501505
'''
502506
# ---
503-
# name: test_render_numpydoc_section_return[name: int\n A description.]
507+
# name: test_render_numpydoc_section_return[name: int\n A `"description"`.]
504508
'''
505509
Code
506510
Parameters
507511
---
508512
name: int
509-
A description.
513+
A `"description"`.
510514

511515
Returns
512516
---
513517
name: int
514-
A description.
518+
A `"description"`.
515519

516520
Attributes
517521
---
518522
name: int
519-
A description.
523+
A `"description"`.
520524

521525
Default
522526
# Parameters {.doc-section .doc-section-parameters}
523527

524-
| Name | Type | Description | Default |
525-
|--------|--------|----------------|------------|
526-
| name | | A description. | _required_ |
528+
| Name | Type | Description | Default |
529+
|--------|--------|--------------------|------------|
530+
| name | | A `"description"`. | _required_ |
527531

528532
# Returns {.doc-section .doc-section-returns}
529533

530-
| Name | Type | Description |
531-
|--------|--------|----------------|
532-
| name | int | A description. |
534+
| Name | Type | Description |
535+
|--------|--------|--------------------|
536+
| name | int | A `"description"`. |
533537

534538
# Attributes {.doc-section .doc-section-attributes}
535539

536-
| Name | Type | Description |
537-
|--------|--------|----------------|
538-
| name | int | A description. |
540+
| Name | Type | Description |
541+
|--------|--------|--------------------|
542+
| name | int | A `"description"`. |
539543

540544
List
541545
# Parameters {.doc-section .doc-section-parameters}
542546

543-
<code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
547+
<code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} []{.parameter-annotation}</code>
544548

545-
: A description.
549+
: A `"description"`.
546550

547551
# Returns {.doc-section .doc-section-returns}
548552

549-
<code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
553+
<code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation}</code>
550554

551-
: A description.
555+
: A `"description"`.
552556

553557
# Attributes {.doc-section .doc-section-attributes}
554558

555-
<code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
559+
<code>[**name**]{.parameter-name} [:]{.parameter-annotation-sep} [int]{.parameter-annotation}</code>
556560

557-
: A description.
561+
: A `"description"`.
558562
'''
559563
# ---

‎quartodoc/tests/example_signature.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,14 @@ class C:
3131
...
3232

3333

34-
def a_complex_signature(x: "list[C | int | None]", y: "pathlib.Pathlib"):
34+
def a_complex_signature(x: "list[C | int | None]", y: "pathlib.Pathlib", z):
3535
"""
3636
Parameters
3737
----------
3838
x:
3939
The x parameter
4040
y:
4141
The y parameter
42+
z:
43+
The z parameter (unannotated)
4244
"""

0 commit comments

Comments
 (0)