Merge pull request #87 from melissawm/document-options

Add comments on mkdocstrings options

mkdocs.yml

@@ -100,45 +100,27 @@ plugins:
             - https://docs.python.org/3/objects.inv
           options:  # See https://mkdocstrings.github.io/python/usage/#globallocal-options
             # General options
-            find_stubs_package: true
-            allow_inspection: true
-            show_bases: true
-            show_source: false
-            preload_modules: ""
+            enable_inventory: true  # Create an objects.inv file
+            show_source: false  # Do now show source code for objects
             # Heading options
-            heading_level: 2
-            parameter_headings: true
-            show_root_heading: false
-            annotations_path: source
-            enable_inventory: true
-            show_root_toc_entry: false
-            show_root_full_path: true
-            show_root_members_full_path: true
-            show_object_full_path: false
-            show_category_heading: false
-            show_symbol_type_heading: true
-            show_symbol_type_toc: false
+            show_root_heading: false  # Do now show module name as heading, default
+            show_root_toc_entry: false  # Do not create anchor for acquire module itself
+            show_root_members_full_path: true  # Show full path for members, i.e.
+                                               # acquire.Camera instead of Camera
+            show_symbol_type_heading: true  # Show the symbol type in headings (i.e. `method`, `class`)
             # Members options
-            inherited_members: false
-            members: true
-            members_order: "alphabetical"
-            filters: ["!^_", "!dict"]  # Remove private members
-            group_by_category: true
-            show_submodules: false
-            summary: true
-            show_labels: false
+            members: true  # An explicit list of members to render (true for all)
+            inherited_members: false  # Do not render any inherited members (for classes)
+            members_order: "alphabetical"  # Order members alphabetically, default
+            filters: ["!^_", "!dict"]  # Remove private and unwanted members
+            summary: true  # Whether to render summaries of objects. Insiders only for now
+            show_labels: false  # Whether to show labels of the members
             # Docstring options
             docstring_style: google
-            # docstring_options: {}
-            docstring_section_style: table
-            merge_init_into_class: false
-            show_if_no_docstring: false
+            # docstring_options: {}  # Can be customized, see https://mkdocstrings.github.io/python/usage/configuration/docstrings/#docstring_options
+            docstring_section_style: table  # The style used to render docstring sections, default
+            show_if_no_docstring: false  # Default
             # Signature/annotation options
-            annotations_path: "brief"
-            line_length: 60
-            show_signature: true
-            show_signature_annotations: true
-            signature_crossrefs: true
-            separate_signature: false
-            unwrap_annotated: false
-            modernize_annotations: false
+            annotations_path: "brief"  # The verbosity for annotations path, default
+            show_signature_annotations: true  # Show the type annotations in methods and functions signatures
+            signature_crossrefs: true  # Whether to render cross-references for type annotations in signatures