From baa7680f82451a8840f05a323181fa0e2a64d344 Mon Sep 17 00:00:00 2001 From: Benjamin Alan Weaver Date: Mon, 23 Oct 2017 13:19:01 -0700 Subject: [PATCH 1/2] add documentation on hyperlinks --- doc/format.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/format.rst b/doc/format.rst index ceb5fe7a..c201ccc9 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -597,6 +597,24 @@ Other points to keep in mind (i.e. scalar types, sequence types), those arguments can be documented with type `array_like`. +* Links : If you need to include hyperlinks in your docstring, note that + some docstring sections are not parsed as standard reST, and in these + sections, numpydoc may become confused by hyperlink targets such as:: + + .. _Example: http://www.example.com + + If the Sphinx build issues a warning of the form + ``WARNING: Unknown target name: "example"``, then that is what is happening. + There are two possible workarounds. First, the inline form can be used:: + + `Example `_ + + Second, the hyperlink target can be placed in a section that *is* parsed + as standard reST, such as **Notes**. The inline form is recommended, since + it is more likely to "just work", and not require trial-and-error + experimentation with target placement. + + Common reST concepts -------------------- For paragraphs, indentation is significant and indicates indentation in the From 256325c584a1aefe59febbf7b091f3d7da4d1027 Mon Sep 17 00:00:00 2001 From: Benjamin Alan Weaver Date: Mon, 23 Oct 2017 13:38:21 -0700 Subject: [PATCH 2/2] only recommend inline form --- doc/format.rst | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index c201ccc9..4eed2036 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -605,15 +605,10 @@ Other points to keep in mind If the Sphinx build issues a warning of the form ``WARNING: Unknown target name: "example"``, then that is what is happening. - There are two possible workarounds. First, the inline form can be used:: + To avoid this problem, use the inline hyperlink form:: `Example `_ - Second, the hyperlink target can be placed in a section that *is* parsed - as standard reST, such as **Notes**. The inline form is recommended, since - it is more likely to "just work", and not require trial-and-error - experimentation with target placement. - Common reST concepts --------------------