Skip to content

Commit f883a65

Browse files
pawamoypawamoy
committed
docs: Make sure each option is documented
1 parent 950f90e commit f883a65

File tree

7 files changed

+94
-31
lines changed

7 files changed

+94
-31
lines changed

‎docs/usage/configuration/docstrings.md

+21-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Docstrings options
22

3+
[](){#option-docstring_style}
34
## `docstring_style`
45

56
- **:octicons-package-24: Type [`str`][] :material-equal: `"google"`{ title="default value" }**
@@ -84,6 +85,7 @@ def greet(name: str) -> str:
8485
////
8586
///
8687

88+
[](){#option-docstring_options}
8789
## `docstring_options`
8890

8991
- **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }**
@@ -158,6 +160,7 @@ ok
158160
////
159161
///
160162

163+
[](){#option-docstring_section_style}
161164
## `docstring_section_style`
162165

163166
- **:octicons-package-24: Type [`str`][] :material-equal: `"table"`{ title="default value" }**
@@ -249,6 +252,7 @@ by reserving more horizontal space on the second column.
249252
////
250253
///
251254

255+
[](){#option-merge_init_into_class}
252256
## `merge_init_into_class`
253257

254258
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -320,6 +324,7 @@ class Thing:
320324
////
321325
///
322326

327+
[](){#option-relative_crossrefs}
323328
## `relative_crossrefs`
324329

325330
[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
@@ -432,6 +437,7 @@ class Class:
432437
433438
INFO: **There is an alternative, third-party Python handler that handles relative references: [mkdocstrings-python-xref](https://github.com/analog-garage/mkdocstrings-python-xref).**
434439
440+
[](){#option-scoped_crossrefs}
435441
## `scoped_crossrefs`
436442
437443
[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
@@ -452,7 +458,7 @@ The following order is applied when resolving a name in a given scope:
452458

453459
In practice, it means that the name is first looked up in members, then it is compared against the parent name (only if it's a class), then it is looked up in siblings. It continues climbing up the object tree until there's no parent, in which case it raises a name resolution error.
454460

455-
Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was [loaded][import]. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a [relative][relative_crossrefs] one instead.
461+
Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was [loaded][inventories]. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a [relative][relative_crossrefs] one instead.
456462

457463
Another limitation is that you won't be able to reference an external package if its name can be resolved in the current object's scope.
458464

@@ -541,6 +547,7 @@ class Class:
541547
542548
///
543549
550+
[](){#option-show_if_no_docstring}
544551
## `show_if_no_docstring`
545552
546553
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -610,6 +617,7 @@ class ClassWithoutDocstring:
610617
////
611618
///
612619

620+
[](){#option-show_docstring_attributes}
613621
## `show_docstring_attributes`
614622

615623
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -662,6 +670,7 @@ class Class:
662670
////
663671
///
664672

673+
[](){#option-show_docstring_functions}
665674
## `show_docstring_functions`
666675

667676
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -736,7 +745,7 @@ class Class:
736745
////
737746
///
738747

739-
748+
[](){#option-show_docstring_classes}
740749
## `show_docstring_classes`
741750

742751
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -795,6 +804,7 @@ class Class:
795804
////
796805
///
797806

807+
[](){#option-show_docstring_modules}
798808
## `show_docstring_modules`
799809

800810
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -851,6 +861,7 @@ Modules:
851861
////
852862
///
853863

864+
[](){#option-show_docstring_description}
854865
## `show_docstring_description`
855866

856867
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -914,6 +925,7 @@ class Class:
914925
////
915926
///
916927

928+
[](){#option-show_docstring_examples}
917929
## `show_docstring_examples`
918930

919931
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -967,6 +979,7 @@ hello
967979
////
968980
///
969981

982+
[](){#option-show_docstring_other_parameters}
970983
## `show_docstring_other_parameters`
971984

972985
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1017,6 +1030,7 @@ def do_something(**kwargs):
10171030
////
10181031
///
10191032

1033+
[](){#option-show_docstring_parameters}
10201034
## `show_docstring_parameters`
10211035

10221036
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1067,6 +1081,7 @@ def do_something(whatever: int = 0):
10671081
////
10681082
///
10691083

1084+
[](){#option-show_docstring_raises}
10701085
## `show_docstring_raises`
10711086

10721087
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1118,6 +1133,7 @@ def raise_runtime_error():
11181133
////
11191134
///
11201135

1136+
[](){#option-show_docstring_receives}
11211137
## `show_docstring_receives`
11221138

11231139
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1177,6 +1193,7 @@ def iter_skip(
11771193
////
11781194
///
11791195

1196+
[](){#option-show_docstring_returns}
11801197
## `show_docstring_returns`
11811198

11821199
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1228,6 +1245,7 @@ def rand() -> int:
12281245
////
12291246
///
12301247

1248+
[](){#option-show_docstring_warns}
12311249
## `show_docstring_warns`
12321250

12331251
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1279,6 +1297,7 @@ def warn():
12791297
////
12801298
///
12811299

1300+
[](){#option-show_docstring_yields}
12821301
## `show_docstring_yields`
12831302

12841303
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

‎docs/usage/configuration/general.md

+5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# General options
22

3+
[](){#option-allow_inspection}
34
## `allow_inspection`
45

56
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -250,6 +251,8 @@ __all__ = ["their_object"]
250251
<p>Docstring of your module.</p>
251252
////
252253
///
254+
255+
[](){#option-show_bases}
253256
## `show_bases`
254257

255258
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -287,6 +290,7 @@ plugins:
287290
////
288291
///
289292

293+
[](){#option-show_inheritance_diagram}
290294
## `show_inheritance_diagram`
291295

292296
[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
@@ -372,6 +376,7 @@ Mixin2A --> Mixin2B
372376
because these classes do not exist in our documentation.*
373377
///
374378

379+
[](){#option-show_source}
375380
## `show_source`
376381

377382
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

‎docs/usage/configuration/headings.md

+10
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Headings options
22

3+
[](){#option-heading_level}
34
## `heading_level`
45

56
- **:octicons-package-24: Type [`int`][] :material-equal: `2`{ title="default value" }**
@@ -57,6 +58,7 @@ plugins:
5758
////
5859
///
5960
61+
[](){#option-parameter_headings}
6062
## `parameter_headings`
6163

6264
[:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)
@@ -179,6 +181,7 @@ To customize symbols, see [Customizing symbol types](../customization.md/#symbol
179181

180182
///
181183

184+
[](){#option-show_root_heading}
182185
## `show_root_heading`
183186

184187
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -242,6 +245,7 @@ plugins:
242245
////
243246
///
244247

248+
[](){#option-show_root_toc_entry}
245249
## `show_root_toc_entry`
246250

247251
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -299,6 +303,7 @@ More text.
299303
////
300304
///
301305

306+
[](){#option-show_root_full_path}
302307
## `show_root_full_path`
303308

304309
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -344,6 +349,7 @@ plugins:
344349
////
345350
///
346351

352+
[](){#option-show_root_members_full_path}
347353
## `show_root_members_full_path`
348354

349355
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -392,6 +398,7 @@ plugins:
392398
////
393399
///
394400

401+
[](){#option-show_object_full_path}
395402
## `show_object_full_path`
396403

397404
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -445,6 +452,7 @@ plugins:
445452
////
446453
///
447454

455+
[](){#option-show_category_heading}
448456
## `show_category_heading`
449457

450458
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -510,6 +518,7 @@ plugins:
510518
////
511519
///
512520

521+
[](){#option-show_symbol_type_heading}
513522
## `show_symbol_type_heading`
514523

515524
[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
@@ -574,6 +583,7 @@ plugins:
574583
////
575584
///
576585

586+
[](){#option-show_symbol_type_toc}
577587
## `show_symbol_type_toc`
578588

579589
[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)

‎docs/usage/configuration/members.md

+8
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Members options
22

3+
[](){#option-members}
34
## `members`
45

56
- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] |
@@ -95,6 +96,7 @@ this_attribute = 0
9596

9697
INFO: **The default behavior (with unspecified `members` or `members: null`) is to use [`filters`][].**
9798

99+
[](){#option-inherited_members}
98100
## `inherited_members`
99101

100102
- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] |
@@ -259,6 +261,7 @@ class Main(Base):
259261

260262
///
261263

264+
[](){#option-members_order}
262265
## `members_order`
263266

264267
- **:octicons-package-24: Type [`str`][] :material-equal: `"alphabetical"`{ title="default value" }**
@@ -329,6 +332,7 @@ def function_c():
329332
////
330333
///
331334

335+
[](){#option-filters}
332336
## `filters`
333337

334338
- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | None</code> :material-equal: `["!^_[^_]"]`{ title="default value" }**
@@ -427,6 +431,7 @@ Here are some common filters that you might to want to use.
427431
- `["!^_[^_]"]`: exclude all private/protected objects, keep special ones (default filters)
428432
///
429433

434+
[](){#option-group_by_category}
430435
## `group_by_category`
431436

432437
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -496,6 +501,7 @@ def function_d():
496501
////
497502
///
498503

504+
[](){#option-show_submodules}
499505
## `show_submodules`
500506

501507
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -550,6 +556,7 @@ package
550556
////
551557
///
552558

559+
[](){#option-summary}
553560
## `summary`
554561

555562
[:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0)
@@ -643,6 +650,7 @@ plugins:
643650
////
644651
///
645652
653+
[](){#option-show_labels}
646654
## `show_labels`
647655
648656
- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

0 commit comments

Comments
 (0)