From f080d34440e0e7f0b86a90630560b4dadf2aa2c5 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 21 May 2019 20:04:10 +0200 Subject: [PATCH] documentation/python: use external summary only if it's actually there. --- documentation/python.py | 2 +- .../test_python/content/classes.html | 1 + .../content/content.AnotherClass.html | 32 +++++++++++++++++++ .../test_python/content/content.html | 2 ++ documentation/test_python/content/content.py | 3 ++ documentation/test_python/content/docs.rst | 4 +++ documentation/test_python/test_content.py | 1 + 7 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 documentation/test_python/content/content.AnotherClass.html diff --git a/documentation/python.py b/documentation/python.py index 9d49ffbf..5c3a2556 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -318,7 +318,7 @@ def parse_pybind_docstring(state: State, name: str, doc: str) -> List[Tuple[str, def extract_summary(state: State, external_docs, path: List[str], doc: str) -> str: # Prefer external docs, if available path_str = '.'.join(path) - if path_str in external_docs: + if path_str in external_docs and external_docs[path_str]['summary']: return render_inline_rst(state, external_docs[path_str]['summary']) if not doc: return '' # some modules (xml.etree) have that :( diff --git a/documentation/test_python/content/classes.html b/documentation/test_python/content/classes.html index 9472999b..ff357b8e 100644 --- a/documentation/test_python/content/classes.html +++ b/documentation/test_python/content/classes.html @@ -24,6 +24,7 @@
  • module content This overwrites the docstring for content.
    • diff --git a/documentation/test_python/content/content.AnotherClass.html b/documentation/test_python/content/content.AnotherClass.html new file mode 100644 index 00000000..1075f475 --- /dev/null +++ b/documentation/test_python/content/content.AnotherClass.html @@ -0,0 +1,32 @@ + + + + + content.AnotherClass | My Python Project + + + + + +
    +
    +
    +
    +
    +

    + content.AnotherClass class +

    +

    This class has summary from the docstring

    +

    This class has external details but summary from the docstring.

    +
    +
    +
    +
    + + diff --git a/documentation/test_python/content/content.html b/documentation/test_python/content/content.html index a44c9171..01edd0af 100644 --- a/documentation/test_python/content/content.html +++ b/documentation/test_python/content/content.html @@ -40,6 +40,8 @@ tho.

    Classes

    +
    class AnotherClass
    +
    This class has summary from the docstring
    class Class
    This overwrites the docstring for content.Class.
    diff --git a/documentation/test_python/content/content.py b/documentation/test_python/content/content.py index ea2d6f1b..185d93a0 100644 --- a/documentation/test_python/content/content.py +++ b/documentation/test_python/content/content.py @@ -3,4 +3,7 @@ class Class: """And this class summary, not shown either""" +class AnotherClass: + """This class has summary from the docstring""" + CONSTANT: float = 3.14 diff --git a/documentation/test_python/content/docs.rst b/documentation/test_python/content/docs.rst index 3c6ceb05..0161c2ce 100644 --- a/documentation/test_python/content/docs.rst +++ b/documentation/test_python/content/docs.rst @@ -10,5 +10,9 @@ This is detailed class docs. Here I *also* hate how it needs to be indented. +.. py:class:: content.AnotherClass + + This class has external details but summary from the docstring. + .. py:data:: content.CONSTANT :summary: This is finally a docstring for ``content.CONSTANT`` diff --git a/documentation/test_python/test_content.py b/documentation/test_python/test_content.py index bdb77724..e61778a1 100644 --- a/documentation/test_python/test_content.py +++ b/documentation/test_python/test_content.py @@ -38,3 +38,4 @@ class Content(BaseInspectTestCase): self.assertEqual(*self.actual_expected_contents('classes.html')) self.assertEqual(*self.actual_expected_contents('content.html')) self.assertEqual(*self.actual_expected_contents('content.Class.html')) + self.assertEqual(*self.actual_expected_contents('content.AnotherClass.html')) -- 2.30.2