Show proper error to user when conf.py is not found #3326

humitos · 2017-11-27T15:51:27Z

I'm using BuildEnvironmentError for now, but we should use
ProjectConfigurationError once the PR got merged: #3310

agjohnson · 2017-12-01T07:03:39Z

I'll wait until #3310 is merged and this is rebased on there for review. Blocking for now -- or feel free to rebase there and we'll swap the PR base after merge of #3310.

humitos · 2017-12-12T17:26:20Z

I added a couple of tests for old behaviour and also to catch this PR behaviour. Besides, I added the exception message as a class attribute.

Please, re-review this PR when you have some time.

(the last commit is styling, so you can skip it from the logic review)

humitos · 2017-12-12T17:26:47Z

Link for logic commits: https://github.com/rtfd/readthedocs.org/pull/3326/files/f44ba0eb3714c7e607925c75d1eec9c65fbe4a35

ericholscher · 2017-12-12T17:52:35Z

readthedocs/projects/exceptions.py

+        "There are more than one conf.py file and none of them say doc "
+        "in their path, we don't know which one use. Please, select "
+        "the correct one under the Advanced settings tab in the "
+        "project's Admin."


We should probably provide a link here.

Do we support HTML content on the message exception? I think no.

For example, we are not using | safe filter at https://github.com/rtfd/readthedocs.org/blob/bb7bb4d6751ecce67ba274a32100406b951f9b90/readthedocs/templates/builds/build_detail.html#L156

Would make for a better UX, perhaps as an idea in the future. We could also add it as a "build tip"

Following with your idea, I'd say that the error is OK but this could be mixed with what you have done for setup.py install and other cases.

I think we should create a "Build tip" concept that checks for this type of errors and show a user friendly-shiny message with links and more.

So, in this particular case, for example, I'd rewrite the exception message to something like:

There are more than one conf.py file and we don't know which one use.

Then, a "Build tip" saying:

Please, select the correct one under the Advanced Settings (link) tab in the project's Admin or re-structure your project to have a docs folder with the conf.py inside it.

I like that idea. I think we need to firm up our usage around build tips and not do the logic in the template though.

ericholscher · 2017-12-12T17:53:37Z

readthedocs/projects/models.py

+            raise ProjectConfigurationError(
+                ProjectConfigurationError.MULTIPLE_CONF_FILES
+            )
+


I feel like we keep changing build logic that breaks people's build. Is there a reason we are wanting to fail builds on this, instead of warning users? I think we probably want to warn them in this case, because changing this logic could easily break hundreds of project's builds for no real reason.

We did this with the setup.py install failures, and I don't think it's a good pattern to follow.

I didn't change the logic here. I just added a better message.

Before this PR, it said "Conf.py not found" but there were more than one conf.py file. Now, it will fail as it was failing before but saying "Hey, too many conf.py files. We don't know which one to pick"

hmm, interesting.

agjohnson

Looks great! 👍 on more tests here.

I noted a copy change, but this looks good otherwise. Let's keep thinking about how to best surface build suggestions, as I think this is a good pattern so far. I'll open a separate ticket to start discussing how to better implement the build changes, as I think too much logic is being hidden in templates currently.

agjohnson · 2017-12-13T18:27:36Z

readthedocs/projects/exceptions.py

+        'There are more than one conf.py file and none of them say doc '
+        "in their path, we don't know which one use. Please, select "
+        'the correct one under the Advanced settings tab in the '
+        "project's Admin."


A few notes on copy here:

More clarity around why this is a problem is good -- that is: "We found more than one conf.py and are not sure which one to use." instead of mentioning docs/

"Please, select the correct one" -> "Please specify the correct file"

agjohnson · 2017-12-13T18:29:54Z

readthedocs/projects/exceptions.py

+        "There are more than one conf.py file and none of them say doc "
+        "in their path, we don't know which one use. Please, select "
+        "the correct one under the Advanced settings tab in the "
+        "project's Admin."


I like that idea. I think we need to firm up our usage around build tips and not do the logic in the template though.

humitos · 2017-12-15T16:31:27Z

This PR should be ready to merge.

The linting error is unrelated.

File "/home/travis/build/rtfd/readthedocs.org/.tox/lint/lib/python2.7/site-packages/pylint_django/plugin.py", line 22, in register

    start = name_checker.config.const_rgx.pattern[:-2]

AttributeError: 'NoneType' object has no attribute 'pattern'

I didn't find why it's failing yet.

stsewd · 2017-12-15T20:29:14Z

readthedocs/projects/models.py

@@ -171,8 +172,8 @@ class Project(models.Model):

    # Other model data.
    path = models.CharField(_('Path'), max_length=255, editable=False,


In some parts the function call is in this way

func(arg1, arg2)

and other parts like this

func( arg1, arg2)

Which style is the correct?

The second one, but with a trailing comma and the ´)´ in the folowing line is closer to what we want. Like this

func( arg1, arg2, )

but we use this only when it doesn't fit in 80 columns.

We have a style guide for this: http://docs.readthedocs.io/en/latest/contribute.html?highlight=contributing#contributing-to-development

We are using pre-commit command that runs a couple of scripts to apply the proper style to the code.

humitos · 2017-12-18T14:23:20Z

The linting error on this PR is solved in #3408

humitos · 2017-12-21T02:28:50Z

I think this PR is read to merge. Can you review it again, please?

RichardLitt added the PR: ready for review label Nov 27, 2017

agjohnson added the Status: blocked Issue is blocked on another issue label Dec 1, 2017

humitos force-pushed the humitos/confpy/better-error branch from c488a9f to 6ba42b3 Compare December 12, 2017 16:45

humitos removed the Status: blocked Issue is blocked on another issue label Dec 12, 2017

humitos requested review from agjohnson and ericholscher December 12, 2017 17:26

ericholscher reviewed Dec 12, 2017

View reviewed changes

agjohnson reviewed Dec 13, 2017

View reviewed changes

humitos force-pushed the humitos/confpy/better-error branch from ee1bbde to 30b908e Compare December 15, 2017 15:24

stsewd reviewed Dec 15, 2017

View reviewed changes

humitos added 6 commits December 20, 2017 17:04

Show proper error to user when conf.py is not found

ad8a789

Fix lint

534ef08

Exception message and tests

d0cda1d

Styling / Autolint

f0f39b5

Small lint fix

3b5c882

Fix error message

21d63bb

humitos force-pushed the humitos/confpy/better-error branch from 30b908e to 21d63bb Compare December 20, 2017 22:07

ericholscher merged commit e0c5658 into master Dec 21, 2017

stsewd deleted the humitos/confpy/better-error branch August 15, 2018 22:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Show proper error to user when conf.py is not found #3326

Show proper error to user when conf.py is not found #3326

humitos commented Nov 27, 2017 •

edited

agjohnson commented Dec 1, 2017

humitos commented Dec 12, 2017

humitos commented Dec 12, 2017

ericholscher Dec 12, 2017

humitos Dec 12, 2017

ericholscher Dec 12, 2017

humitos Dec 12, 2017 •

edited

agjohnson Dec 13, 2017

ericholscher Dec 12, 2017

humitos Dec 12, 2017

ericholscher Dec 12, 2017

agjohnson left a comment

agjohnson Dec 13, 2017

agjohnson Dec 13, 2017

humitos commented Dec 15, 2017

stsewd Dec 15, 2017

humitos Dec 15, 2017

humitos commented Dec 18, 2017

humitos commented Dec 21, 2017

		@@ -171,8 +172,8 @@ class Project(models.Model):

		# Other model data.
		path = models.CharField(_('Path'), max_length=255, editable=False,

Show proper error to user when conf.py is not found #3326

Show proper error to user when conf.py is not found #3326

Conversation

humitos commented Nov 27, 2017 • edited

agjohnson commented Dec 1, 2017

humitos commented Dec 12, 2017

humitos commented Dec 12, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos Dec 12, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos commented Dec 15, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos commented Dec 18, 2017

humitos commented Dec 21, 2017

humitos commented Nov 27, 2017 •

edited

humitos Dec 12, 2017 •

edited