search

friendly-traceback / docs

Documentation for friendly-traceback and related projects
Creative Commons Zero v1.0 Universal
0 stars 2 forks source link

Add a section describing custom error registration #1

Closed hoefling closed 3 years ago

hoefling commented 3 years ago

@aroberge this is by far not complete, but rather the first draft to reiterate on your feedback.

aroberge commented 3 years ago

I am currently on the road. I will be back on Wednesday and will look at it then. Sorry about that.

On Sat, Jul 17, 2021, 1:14 PM Oleg Höfling, @.***> wrote:

@.**** commented on this pull request.

In source/conf.py https://github.com/friendly-traceback/docs/pull/1#discussion_r671721219:

@@ -48,6 +49,7 @@

ones.

extensions = [ "sphinx.ext.autodoc",

  • "sphinx.ext.intersphinx",

@aroberge https://github.com/aroberge using intersphinx may be an overkill - used that to reference OSError and ConnectionError to indicate those are real :-) Say the word and I'll remove that.

In source/conf.py https://github.com/friendly-traceback/docs/pull/1#discussion_r671721339:

@@ -214,3 +216,10 @@

If true, todo and todoList produce output, else they produce nothing.

todo_include_todos = True + +autodoc_typehints = "none"

@aroberge https://github.com/aroberge this doesn't do anything for now, but when I add type hints in friendly_traceback, Sphinx will start to spit warnings since the types can't be resolved, so turned off type hints preliminary.

In source/custom_errors.rst https://github.com/friendly-traceback/docs/pull/1#discussion_r671721455:

+.. code-block:: +

  • import requests
  • def fetch_data():
  • response = requests.get("https://my-services/api")
  • response.raise_for_status()
  • return response.json()
  • fetch_data()

  • +When the connection can not be established, a :exc:requests.ConnectionError will be raised. +Fortunately, since it inherits from :exc:OSError, friendly is able to provide a hint +about the error cause:

  • An exception of type ConnectionError is a subclass of OSError. An OSError

@aroberge https://github.com/aroberge IMO the quoted output looks ugly

  • would you recommend using terminal screenshots instead?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/friendly-traceback/docs/pull/1#pullrequestreview-708956854, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAEZXQV5N64WVOCJK57LZ5DTYG267ANCNFSM5ARH3Y5Q .

hoefling commented 3 years ago

@aroberge no worries! I think this PR isn't ready to be merged anyway, so no rush. Have a nice trip!

aroberge commented 3 years ago

@hoefling Sorry, I completely forgot about the PR for the documentation when I came back. It has now been merged. Thank you for doing this.

aroberge commented 3 years ago

I've inverted the cause/suggest text that you had written so as to better follow the existing examples -- even though, it would make a lot of sense for advanced users to have the information shown the way you had it written. I've also added a few sidebars. The result is shown here: https://friendly-traceback.github.io/docs/custom_errors.html

As you suggested, I will likely use a screenshot in a later version.