User log and feature requests from Hypothesis

[Zac-HD]

Thanks for building sphinx-codeautolink! It's a super exciting project, and I'm looking forward to adopting it in Hypothesis. While experimenting with that, I encountered a few things that I thought might be useful to report:

• How hard would it be to support .. code-block:: pycon? IIRC blacken-docs has some useful code...
• Maybe store the cache json in Sphinx' doctreedir, which is probably already .gitignored
• To reduce the number of new imports I need, I added

  rst_prolog = """
  .. concat-blocks:: on
  .. implicit-import:: from hypothesis import *
  .. implicit-import:: from hypothesis.strategies import *
  """

  to my conf.py file, so that all our common names would be in scope. However, it looks like from ... import * isn't yet supported and using rst_prolog like this doesn't work for some reason?
  If it did this would be a neat pattern to document though - do you know if there's something I should try instead?
• We're heavy users of decorators so I reported Decorators are not linked, emit RuntimeWarning #28

[felix-hilden]

Hi Zac, and thanks for your kind words! Yeah I'm quite excited too 😄

• pycon: definitely would be cool to have it 👍 I'm not sure about the difficulty
• file in doctreedir: an ace suggestion, wish I had thought of that 😅
• rst_prolog: that seems like a neat idea, I'll see how it works. If it doesn't work out of the box, I'm guessing Sphinx has some tricks instead of just adding it to every source it reads.
• import *: I'm not sure if we'll support this, because it doesn't explicitly bind names. But since we import the library anyway, we could try to see what's assigned. I'll have a look at how the import machinery works in that case and let's discuss here 👍

[Zac-HD]

Yep, that would be even better - though as above I'd want multiple imports and ideally star-imports too 😉

[felix-hilden]

That was surprisingly fast! (#30, #31, #32) Now the only thing between us and the next release is the renaming issue #27. If you don't get to it first, I'll try building Hypothesis docs with the current master tomorrow evening to see if the changes landed right. But now I'm off for the night. Again, huge thanks for the ideas!

[Zac-HD]

Works beautifully - see HypothesisWorks/hypothesis#3112

[Zac-HD]

Though decorators don't have the highlight-on-hover that other names get, if that's an issue - certainly not a blocker for me though.

[felix-hilden]

I'm glad! Hmm, I'll add that to our catch-all CSS issue #3 😄

[Zac-HD]

Version 0.3.0 looks great! I have a few remaining non-blocking warnings; here are reproducing examples if you want to do something about them. I'm not waiting though - feel free to add Hypothesis to a list of users, and thanks again!

---

In the following snippet, I get a RuntimeWarning: Could not match transformation of 'compile' and no link for compile (though match) works, maybe due to name collision with a builtin or the resulting different syntax highlighting?

.. code-block:: python

    from re import compile, match

    compile("abc")
    match("a", "b")

---

"Fluent interfaces" where method calls are chained together tend to emit warnings like RuntimeWarning: sphinx-codeautolinks: multiline names are not supported, found 'map' in document reproducing on lines 3 - 5

.. code-block:: python

    from hypothesis.strategies import integers

    even_ints = integers(
        **kwargs
    ).map(lambda x: x * 2)

---

Doctest blocks aren't supported yet, but it would be a nice feature 😉 The catch: if you use pycon instead, the doctest <BLANKLINE> will produce RuntimeWarning: Could not match a code example to HTML in document, because it's replaced with a truly blank line when building HTML.

.. code-block:: doctest

    >>> print("a\n\nb")
    a
    <BLANKLINE>
    b

(which I discovered because we have a pycon block that used to be a doctest - Sphinx does the replacement in those too)

[felix-hilden]

Perfect! Thank you once more for being objectively the most helpful first user a library could ever ask for 😄

[Zac-HD]

Ooh, actually, here's a feature request: I just tried clicking on a name in an import statement, but they're not linked at the moment. Ideally I'd be able to click on both math and nan in from math import nan 😁

[felix-hilden]

I think you'll get a notification for this already, but I thought I'd let you know that imports are now linked! (#42) Next I want to do the stuff in #44 though, so a release won't happen immediately.

[felix-hilden]

Hi again @Zac-HD, just as a heads up: I recently released 0.5.0 with import linking.

[Zac-HD]

Nice! No problems with the update - in fact it helped me notice that we were accidentally declaring a top-level .. module:: hypothesis 😅 HypothesisWorks/hypothesis#3138