fix autosummary tables and add a note about tabs' toctree (#42)

* add rule to fix #35

* resolve #33

* increase selector specificity

* shorten line length for selector

* decrease line length further

* pleasing stylelint

* remove rogue blank line

docs/customization.rst

@@ -240,6 +240,16 @@ Configuration Options
         - `navigation.sections <https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections>`_
         - `navigation.tabs <https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs>`_
           (only shows for browsers with large viewports)
+
+          .. note::
+              Due to a difference in general document structure between mkdocs and sphinx, any
+              `toctree` entry should start with a page entity (that contains a section header).
+              Sphinx does allow `toctree` entries to be a list of only hyperlinks, but a
+              navigation tab created from such an entry will only lead to the first hyperlink in
+              the `toctree`.
+
+              See `issue #33 <https://github.com/jbms/sphinx-immaterial/issues/33>`_ for a
+              problematic demonstration.
         - `navigation.tabs.sticky <https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#sticky-navigation-tabs>`_
         - `navigation.top <https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button>`_
         - `navigation.tracking <https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-tracking>`_

src/assets/stylesheets/main/_api.scss

@@ -210,3 +210,15 @@ $objinfo-icon-size: 16px;
   border: 1px solid var(--md-default-fg-color--light);
   border-radius: 2px;
 }
+
+// a rule specifically designed for autosummary tables
+// this overrides `.md-typeset code { word-break: break-word; }`
+table.longtable.docutils.data.align-default {
+  tbody > tr > td > p > a.reference.internal {
+    > code.xref.py.py-obj.docutils.literal.notranslate {
+      > span.pre {
+        word-break: normal;
+      }
+    }
+  }
+}