feat(python handler): Root children full path (#136)

Implements the Python handler option `show_root_members_full_path`:
shows the full Python path of the direct children of the object at the
root of the documentation tree. Defaults to false.

Issue #134
PR #136

CREDITS.md

@@ -82,7 +82,7 @@ These projects were used to build `mkdocstrings`. **Thank you!**
 [`pluggy`](https://github.com/pytest-dev/pluggy) |
 [`prompt-toolkit`](https://github.com/prompt-toolkit/python-prompt-toolkit) |
 [`ptyprocess`](https://github.com/pexpect/ptyprocess) |
-[`py`](http://py.readthedocs.io/) |
+[`py`](https://py.readthedocs.io/) |
 [`pycodestyle`](https://pycodestyle.readthedocs.io/) |
 [`pydocstyle`](https://github.com/PyCQA/pydocstyle/) |
 [`pyflakes`](https://github.com/PyCQA/pyflakes) |

src/mkdocstrings/handlers/python.py

@@ -39,6 +39,7 @@ class PythonRenderer(BaseRenderer):
         "show_root_heading": False,
         "show_root_toc_entry": True,
         "show_root_full_path": True,
+        "show_root_members_full_path": False,
         "show_object_full_path": False,
         "show_category_heading": False,
         "show_if_no_docstring": False,
@@ -55,6 +56,7 @@ class PythonRenderer(BaseRenderer):
     **`show_root_toc_entry`** | `bool` | If the root heading is not shown, at least add a ToC entry for it. | `True`
     **`show_root_full_path`** | `bool` | Show the full Python path for the root object heading. | `True`
     **`show_object_full_path`** | `bool` | Show the full Python path of every object. | `False`
+    **`show_root_members_full_path`** | `bool` | Show the full Python path of objects that are children of the root object (for example, classes in a module). When False, `show_object_full_path` overrides. | `False`
     **`show_category_heading`** | `bool` | When grouped by categories, show a heading for each category. | `False`
     **`show_if_no_docstring`** | `bool` | Show the object heading even if it has no docstring or children with docstrings. | `False`
     **`show_source`** | `bool` | Show the source code of this object. | `True`

src/mkdocstrings/templates/python/material/attribute.html

@@ -6,6 +6,10 @@
 
       {% if root %}
         {% set show_full_path = config.show_root_full_path %}
+        {% set root_members = True %}
+      {% elif root_members %}
+        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+        {% set root_members = False %}
       {% else %}
         {% set show_full_path = config.show_object_full_path %}
       {% endif %}

src/mkdocstrings/templates/python/material/class.html

@@ -6,6 +6,10 @@
 
       {% if root %}
         {% set show_full_path = config.show_root_full_path %}
+        {% set root_members = True %}
+      {% elif root_members %}
+        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+        {% set root_members = False %}
       {% else %}
         {% set show_full_path = config.show_object_full_path %}
       {% endif %}

src/mkdocstrings/templates/python/material/function.html

@@ -6,6 +6,10 @@
 
       {% if root %}
         {% set show_full_path = config.show_root_full_path %}
+        {% set root_members = True %}
+      {% elif root_members %}
+        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+        {% set root_members = False %}
       {% else %}
         {% set show_full_path = config.show_object_full_path %}
       {% endif %}

src/mkdocstrings/templates/python/material/method.html

@@ -6,6 +6,10 @@
 
       {% if root %}
         {% set show_full_path = config.show_root_full_path %}
+        {% set root_members = True %}
+      {% elif root_members %}
+        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+        {% set root_members = False %}
       {% else %}
         {% set show_full_path = config.show_object_full_path %}
       {% endif %}

src/mkdocstrings/templates/python/material/module.html

@@ -6,6 +6,10 @@
 
       {% if root %}
         {% set show_full_path = config.show_root_full_path %}
+        {% set root_members = True %}
+      {% elif root_members %}
+        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+        {% set root_members = False %}
       {% else %}
         {% set show_full_path = config.show_object_full_path %}
       {% endif %}